../_images/logo.png

../_images/Server_Architecture_thumbnail_Jun-12-2025.png

netconfd-pro Introduction

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

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

netconfd-pro Features

The netconfd-pro server has the following features:

Protocol Features

NETCONF

RESTCONF

Other Protocols

Server Platform Services

Datastores

Error Handling

Logging

  • Multiple independent Logging streams

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

  • SYSLOG Support using built-in or system API library functions

  • Audit Log with configurable audit log events

  • Bootstrap CLI to allow some critical CLI parameters to take effect immediately (before the YANG compiler and other services are ready)

  • Special PTHREADS logging support

  • Support for logrotate integration

Notifications

Platform

Security

YANG Automation

  • Full, automatic run-time support for any YANG-defined 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

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

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

  • 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

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

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

  • Built-in automation for a large set of YANG extensions

  • Built-in support for OpenConfig YANG Extensions

  • Supports YANG 1.1 Actions defined in RFC 7950

  • Complete XML 1.0 implementation with full support for XML Namespaces

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

Monitoring Features

Supported Standards

This section provides a summary of the networking standards supported by the netconfd-pro server.

gNMI

This OpenConfig standard defines a network management interface.

gRPC

This OpenConfig standard defines a remote procedure call interface.

  • gRPC

  • This protocol is enabled if gRPC is used

  • The gRPC protocol is fully supported

RFC 4252 - RFC 4254 Secure Shell

These standards are implemented by the OpenSSH server.

  • RFC 4252: The Secure Shell (SSH) Authentication Protocol

  • RFC 4253: The Secure Shell (SSH) Transport Layer Protocol

  • RFC 4254: The Secure Shell (SSH) Connection Protocol

The netconfd-pro server uses SSH to support NETCONF over SSH sessions. All functionality required by RFC 6242 is implemented.

RFC 4741 NETCONF Base 1.0

This standard provides the first version of the NETCONF protocol, called 'base:1.0'.

  • RFC 4741: NETCONF Configuration Protocol

  • This protocol can be disabled by setting the --with-netconf CLI parameter to 'false'.

  • This RFC is fully supported

RFC 4742 NETCONF over SSH v1

This standard provides the first version of the NETCONF over SSH transport.

  • RFC 4742: Using the NETCONF Configuration Protocol over Secure SHell (SSH)

  • This protocol version is still in wide use because the framing mechanism does not require that the length of the message in advance.

  • This RFC is fully supported

RFC 5277 NETCONF Notifications

This standard provides the first version of NETCONF Notifications.

RFC 5539 NETCONF over TLS

This standard provides the first NETCONF Over TLS protocol mapping.

RFC 5717 Partial Lock

This standard provides a Database Locking mechanism for locking individual subtrees within the 'running' datastore, instead of the entire datastore.

RFC 5789 PATCH Method for HTTP

This standard provides the PATCH method used by the RESTCONF protocol.

  • RFC 5789: PATCH Method for HTTP

  • All functionality required by RFC 8040 is supported.

RFC 6020 YANG 1.0

This standard provides the first version of the YANG data modeling language. This version is not obsolete, but the RFC 7950 version SHOULD be used instead.

  • RFC 6020: YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)

  • This RFC is fully supported

RFC 6021 YANG Data Types v1

This standard provides the first version of the YANG data types.

RFC 6022 NETCONF Monitoring

This standard provides monitoring information for the server.

RFC 6241 NETCONF base 1.1

This standard defines the current version (called 'base:1.1') of the NETCONF protocol.

RFC 6242 NETCONF over SSH v1.1

This standard provides the current version of the NETCONF over SSH transport.

  • RFC 6242: Using the NETCONF Protocol over Secure Shell (SSH)

  • The updated framing mechanism is much better than the 'base:1.0' message framing, and allows a message to be sent in multiple chunks. The server usually sends a chunk when one output buffer is ready.

  • This RFC is fully supported

RFC 6243 With-Defaults

This standard provides mechanisms to retrieve YANG default values from the server.

RFC 6470 Base Notifications

This standard provides standard notification events for the NETCONF event stream.

RFC 6536 NACM v1

This standard provides the first version of the NETCONF Access Control model.

RFC 6643 SMIv2 to YANG

This standard provides a translation from SMIv2 MIB modules to YANG syntax.

  • RFC 6643: Translation of Structure of Management Information Version 2 (SMIv2) MIB Modules to YANG Modules

  • The translated modules are fully supported

RFC 6991 YANG Data Types v2

This standard provides the second version of the YANG data types.

RFC 7223 Interface Module v1

This standard provides a YANG module for managing network interfaces. It has been replaced by RFC 8343.

  • RFC 7223: A YANG Data Model for Interface Management

  • The module ietf-interfaces.yang is defined.

  • The 'ietf-interfaces' module is partially supported:

    • monitoring is fully supported

    • some configuration parameters are supported

RFC 7224 Interface Types

This standard provides the initial version of the identity definitions for the 'interface-type' data type.

  • RFC 7224: IANA Interface Type YANG Module

  • The module 'iana-if-type.yang' is defined.

  • Many revisions of this module have been published

  • The current version of this module is provided by IANA

  • This RFC is fully supported

RFC 7230 - RFC 7231 HTTP 1.1

These standards provide the HTTP protocol used by RESTCONF.

  • RFC 7230: Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing

  • RFC 7231: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content

  • These RFCs are fully supported by the configured WEB server in the RESTCONF Installation. Many HTTP headers are processed by the RESTCONF server, using the 'FastCGI' programming interface.

RFC 7232 Conditional Requests

This standard provides conditional RESTCONF requests using RESTCONF Headers, which allow a client to optimize data transfers.

  • RFC 7232: Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests

  • All functionality required by RFC 8040 is supported.

RFC 7317 System Module

This standard provides a YANG module for system management.

  • RFC 7317: A YANG Data Model for System Management

  • The module iana-crypt-hash.yang is defined.

  • The module ietf-system.yang is defined.

  • The 'iana-crypt-hash' module is fully supported:

    • Loaded automatically by the server

  • The 'ietf-system' module is partially supported:

    • Monitoring is partially supported

    • RPC operations are fully supported

    • Some configuration parameters are supported

    • Requires --module='ietf-system' parameter to load

RFC 7407: X.509 Cert to Name

This standard provides configuration parameters for mapping X.509 certificate fields to user names. It is adapted from SNMP to NETCONF.

  • RFC 7407: A YANG Data Model for SNMP Configuration

  • The module ietf-x509-cert-to-name.yang is defined.

  • The module 'ietf-snmp.yang' is defined.

  • The 'ietf-x509-cert-to-name' module is fully supported

  • The 'ietf-snmp' module is not supported

RFC 7589 NETCONF over TLS v2

This standard provides the current NETCONF Over TLS protocol mapping.

  • RFC 7589: Using the NETCONF Protocol over Transport Layer Security (TLS) with Mutual X.509 Authentication

  • This protocol must be enabled using the --with-netconf-tls CLI parameter.

  • Some steps are required to Configure TLS for the client and server.

  • Several CLI parameters are provided for TLS Configuration

  • This RFC is fully supported

RFC 7895 YANG Library v1

This standard provides the first version of the YANG Library. It is used to provide clients with an inventory of the YANG modules used by the server.

  • RFC 7895: YANG Module Library

  • The module ietf-yang-library.yang is defined, dated '2016-06-21'.

  • The new module contains all the contents of this module, but with 'deprecated' status.

  • The --with-new-yanglib CLI parameter must be set to 'false' to force this module revision to be used.

  • This RFC is fully supported, but it has been obsoleted by RFC 8525.

RFC 7950 YANG 1.1

This standard provides the current version of the YANG data modeling language.

  • RFC 7950: The YANG 1.1 Data Modeling Language

  • This RFC is fully supported

RFC 7951 YANG JSON Encoding

This standard provides JSON encoding of YANG data. This is used by the RESTCONF protocol.

  • RFC 7951: JSON Encoding of Data Modeled with YANG

  • This RFC is fully supported

RFC 7952 YANG Metadata

This standard provides definitions for Using YANG Metadata. This is used by the NETCONF protocol.

  • RFC 7952: Defining and Using Metadata with YANG

  • The module ietf-yang-metadata.yang is defined

  • This RFC is partially supported:

    • The md:annotation extension is fully supported

    • XML encoding of metadata is fully supported

    • JSON encoding of metadata is not yet supported

RFC 8040 RESTCONF

This standard defines the RESTCONF protocol.

RFC 8071 Call Home

This standard provides the IETF Call Home feature, which allows a server to initiate the transport session to a client.

RFC 8072 YANG Patch

This standard defines the YANG Patch mechanism for editing multiple resources at once. It is used by the RESTCONF and High Availability (YP-HA) features.

  • RFC 8072: YANG Patch Media Type

  • This RFC is fully supported

RFC 8341 NACM v2

This standard provides the current version of the NETCONF Access Control model.

RFC 8342 NMDA

This standard defines the NMDA datastore architecture.

  • RFC 8342: Network Management Datastore Architecture (NMDA)

  • The module ietf-datastores.yang is defined

  • The module ietf-origin.yang is defined

  • This feature can be enabled by setting the --with-nmda CLI parameter to 'true'.

  • The 'ietf-origin' module is fully supported

  • The 'ietf-datastores' module is partially supported:

    • The conventional datastores are fully supported

    • The 'operational' datastore is fully supported

    • The 'intended' datastore is a mirror of the 'running' datastore, and is not fully supported.

RFC 8343 Interface Module v2

This standard provides a YANG module for managing network interfaces.

  • RFC 8343: A YANG Data Model for Interface Management

  • The module ietf-interfaces.yang is defined.

  • The 'ietf-interfaces' module is partially supported:

    • monitoring is fully supported

    • some configuration parameters are supported

RFC 8525 YANG Library v2

This standard provides the current version of the YANG Library. It is used to provide clients with an inventory of the YANG modules used by the server.

RFC 8526 NETCONF NMDA

This standard provides NETCONF protocol operations for accessing NMDA datastores.

RFC 8527 RESTCONF NMDA

This standard provides RESTCONF protocol operations for accessing NMDA datastores.

  • RFC 8527: RESTCONF Extensions to Support the Network Management Datastore Architecture

  • This RFC is partially supported:

    • Retrieval operations (GET, HEAD) are supported

    • Edit operations are not supported

    • The YANG metadata is supported

RFC 8528 Schema Mount

This standard defines the YANG Schema Mount feature.

RFC 8639 Notification Subscriptions

This standard defines notification Subscriptions for use with NETCONF and RESTCONF. They are called RFC 8639 Subscriptions or 'new' subscriptions.

RFC 8640 NETCONF Subscriptions

This standard defines requirements for using RFC 8639 with the NETCONF protocol.

  • RFC 8640: Dynamic Subscription to YANG Events and Datastores over NETCONF

  • This RFC is partially supported:

    • All mandatory functionality is supported

    • All event stream and YANG Push functionality is fully supported

    • Error info fields using specified error identities are not supported

RFC 8641 YANG Push

This standard defines notifications to YANG datastores. It is called YANG Push.

RFC 8650 RESTCONF Subscriptions

This standard defines requirements for using RFC 8639 with the RESTCONF protocol. RESTCONF Subscriptions use the <establish-subscription> operation similar to NETCONF, except a URI is returned to use for retrieval.

RFC 8791 YANG Structures

This standard defines YANG extensions that allow abstract structures to be defined and augmented. These structures are often used to model artifacts and protocol messages. Regular YANG data nodes are included in datastores, but not YANG structures.

RFC 8808 Factory Default

This standard defines the factory default datastore support.

RFC 8819 Module Tags

This standard defines mechanisms and YANG extensions for classifying YANG modules. These mappings can be used for module tag filtering.

  • RFC 8819: YANG Module Tags

  • The module 'ietf-module-tags.yang' is defined

  • The --with-modtags CLI parameter is used to enable module tag support

  • The --module-tagmap CLI parameter is used to configure module-tag assignments.

  • The 'module-tag' leaf-list parameter is supported for the following operations:

  • The <get-module-tags> operation is provided to retrieve the module tag mappings in use

  • The 'ietf-module-tags' module is not supported

RFC 8949 CBOR

This standard defines the binary data encoding used by RFC 9254.

  • RFC 8949: Concise Binary Object Representation (CBOR)

  • This encoding is only used if Binary Push is used.

  • This RFC is fully supported

RFC 9196 Notification Capabilities

This standard defines a YANG module for monitoring the notification capabilities of the server.

  • RFC 9196: YANG Modules Describing Capabilities for Systems and Datastore Update Notifications

  • The module ietf-system-capabilities.yang is defined

  • The module ietf-notification-capabilities.yang is defined

  • The 'ietf-system-capabilities' module is partially supported:

    • global capabilities are supported

    • per-node capabilities are not supported

  • The 'ietf-notification-capabilities' module is fully supported.

RFC 9254 YANG CBOR

This standard defines CBOR encoding of YANG instance data.

  • RFC 9254: Encoding of Data Modeled with YANG in the Concise Binary Object Representation (CBOR)

  • The CBOR encoding is used by the Binary Push feature

  • This RFC is fully supported

RFC 9595 YANG SID Files

This standard defines mechanisms for managing and defining YANG SID files.

XML 1.0

This standard defines the XML encoding used by the NETCONF and RESTCONF protocols.

XPath

This standard defines the XML Path language used in YANG and NETCONF XPath filtering.

Server Programs

../_images/Server_Architecture_Programs.png

The server can be deployed in many different ways. In every case, the 'netconfd-pro' program is used. Depending on the protocols used and the deployment choices, there will be additional programs used.

The server programs have been moved to the YumaPro Programs section. They are just listed here.

Setting the Server Profile

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Loading YANG Modules

Loading Modules at Boot-Time

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

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

Loading Modules at Run-Time

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

Loading Bundles at Boot-Time

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

Loading Bundles at Run-Time

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

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

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

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

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

Unloading YANG Modules

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

Modules imported by the module being unloaded are not unloaded.

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

Modules imported by the bundle are unloaded.

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

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

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

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

Starting netconfd-pro

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

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

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

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

Starting netconfd-pro Examples

The netconfd-pro program can be invoked several ways:

  • To get the current version and exit:

netconfd-pro --version

  • To get program help and exit:

netconfd-pro --help
netconfd-pro --help --brief
netconfd-pro --help --full

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

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

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

netconfd-pro

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

netconfd-pro --log=mylogfile

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

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

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

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

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

netconfd-pro --fileloc-fhs=true

Starting netconfd-pro With A Log File

The netconfd-pro program is usually started at system boot time. The main logging output is usually sent to a log file, or 'syslog', or both.

  • If no logging parameters are specified, then the default is to set the main logging output to 'stdout', and the --log-level to 'info'.

Copyright Notices

The logging output includes copyright messages that cannot be removed from the program.

Example: starting netconfd-pro with all default parameters:

andy@andy-i9-homedev:~$ netconfd-pro


Starting netconfd-pro...
Copyright (c) 2008-2012, Andy Bierman, All Rights Reserved.
Copyright (c) 2012-2023, YumaWorks, Inc., All Rights Reserved.

Note

  • The startup banner will be displayed to 'stdout' if logging parameters are provided in the config file.

  • Put logging parameters on the command line to avoid any copyright output to 'stdout'.

Provide the following logging parameters on the command line to avoid any output to 'stdout' when the program starts.

Example:

> netconfd-pro --log=/home/user/test1.log

Starting SIL-SA Subsystems with sil-sa-app

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

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

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

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

  • --address=ip-address

    • The IP address of the main server.

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

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

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

  • --library=string

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

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

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

    • Example:

      # select libfoo_sa.so
--library=foo

  • --log-level=enum

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

  • --log=filespec

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

  • --port=uint16

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

    • The default is 2023.

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

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

  • --subsys-id=string

    • The subsystem identifier to use.

    • The default is subsys1.

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

The SIL-SA libraries loaded depends on 2 factors:

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

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

Example: Start the server with a non-default socket

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

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

Example 2: Start 2 subsystems on the same host

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

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

Starting SIL-SA Subsystems with py-sil-app

For more details on how to use py-sil-app refer to Starting PY-SIL Subsystems with py-sil-app

Stopping netconfd-pro

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

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

Signal Handling

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

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

Signals Recognized by netconfd-pro

Signal

Number

Description

SIGHUP (Hangup)

1

Restart the server.

SIGINT (Control-C)

2

Shutdown the server.

SIGQUIT

3

Shutdown the server.

SIGILL

4

Shutdown the server.

SIGTRAP

5

Shutdown the server.

SIGABRT

6

Shutdown the server.

SIGKILL

9

Kill the server process (No proper cleanup!)

SIGUSR1

10

Reload the server (Does a restart)

SIGUSR2

12

Logrotate (reopen log files)

SIGPIPE

13

Handle I/O connection error.

SIGTERM

15

Shutdown the server.

SIGVTALRM

26

Internal threads kill signal

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

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

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

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

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

Starting netconfd-pro with ypwatcher program

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

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

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

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

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

netconfd-pro

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

netconfd-pro --no-watcher

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

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

netconfd-pro --watcher-interval=10

Signal Handling with ypwatcher program

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

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

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

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

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

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

Signals Recognized by ypwatcher

Signal

Number

Description

SIGBUS

7

Bus error.

SIGFPE

8

Floating Point exception.

SIGKILL

9

Kill

SIGSEGV

11

Invalid memory reference

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

netconfd-pro Error Handling

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

The following CLI parameters affect error handling:

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

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

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

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

Refer to the Error Reporting CLI Parameters section for the complete list of CLI parameters that affect error handling and error reporting.

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

  • Incoming PDU validation

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

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

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

  • Server instrumentation PDU validation

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

  • Database validation

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

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

    • The specific conditions checked automatically are:

      • referential integrity condition test failed (must)

      • missing leaf (mandatory)

      • missing choice (mandatory)

      • extra container or leaf

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

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

      • instance not unique (unique)

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

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

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

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

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

  • Server instrumentation database validation and activation

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

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

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

Module Summary

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

Pre-loaded YANG Modules

Module

Description

iana-crypt-hash.yang

IANA crypt-hash data type

ietf-datastores.yang

NMDA datastore meta-data

ietf-distributed-notif.yang

Message Publisher ID support for YANG Push 2

ietf-factory-default.yang

Contains Factory Default Support

ietf-inet-types.yang

Standard data types

ietf-netconf-acm.yang

Standard NETCONF access control model

ietf-netconf-monitoring.yang

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

ietf-netconf-nmda.yang

NMDA operations for NETCONF, including <get-data>

ietf-netconf-notifications.yang

Standard NETCONF notifications for system events

ietf-netconf-partial-lock.yang

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

ietf-netconf-with-defaults.yang

<with-defaults> extension

ietf-origin.yang

NMDA <operational> origin meta-data

ietf-sid-file.yang

YANG SID File support for Binary Push

ietf-subscribed-notif-receivers.yang

Notification Receiver groupings for UDP-Notif Protocol

ietf-subscribed-notifications.yang

Dynamic Notification Subscriptions from RFC 8639

ietf-system-capabilities.yang

System Capabilities Monitoring

ietf-udp-client.yang

UDP Receiver groupings for Configured Subscriptions

ietf-udp-notif-transport.yang

Main module for UDP-Notif Protocol

ietf-x509-cert-to-name.yang

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

ietf-yang-library.yang

Standard NETCONF YANG Module Library that represents the current set of modules and submodules.

ietf-yang-library-augmentedby.yang

Augments the YANG Library with the 'augmented-by' leaf-list

ietf-yang-metadata.yang

Standard YANG Module containing the md:annotation extension.

ietf-yang-push.yang

Subscriptions to YANG Datastores from RFC 8641

ietf-yang-push-revision.yang

Required Module Revisions for notification subscriptions

ietf-yang-schema-mount.yang

YANG Schema Mount from RFC 8528

ietf-yang-types.yang

Standard data types

nc-notifications.yang

Standard replay notifications

netconfd-pro.yang

Server CLI parameters

notifications.yang

Standard notification operations

openconfig-extensions.yang

Many OC extensions supported (used in other modules)

yuma-ncx.yang

Yuma NETCONF extensions

yuma-app-common.yang

Common CLI parameters

yuma-types.yang

Yuma common data types

yuma-mysession.yang

Get and Set session-specific parameters

yuma-system.yang

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

yuma-time-filter.yang

Get only if datastore changed since a specified timestamp

yumaworks-app-common.yang

Common definitions used by yumapro modules

yumaworks-attrs.yang

Extensions to add last-modified and etag attributes

yumaworks-callhome.yang

Runtime configuration of Call Home server parameters

yumaworks-cert-usermap.yang

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

yumaworks-compare.yang

NETCONF <compare-config> operation to compare configurations

yumaworks-config-change.yang

Add edit data to the netconf-config-change notification

yumaworks-event-filter.yang

Event filters to suppress generation of notifications for the specified events

yumaworks-event-stream.yang

NETCONF Event stream configuration

yumaworks-extensions.yang

YANG extensions for meta-data data tagging

yumaworks-getbulk.yang

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

yumaworks-ids.yang

Session type extensions for the standard monitoring module

yumaworks-lock.yang

NETCONF <lock-all> and <unlock-all> operations to simplify datastore locking for editing

yumaworks-restconf-commit.yang

Extensions to add confirmed-commit procedure to RESTCONF

yumaworks-rfc8639-dev.yang

Deviations for ietf-subscribed-notifications.yang to identify currently unimplemented portions

yumaworks-schema-mount.yang

Contains the sm-config Structure for Schema Mount configuration

yumaworks-sm-yanglib.yang

Contains the <get-sm-yanglib> operation to retrieve Schema Mount YANG libray information

yumaworks-support-save.yang

Contains the <get-support-save> operation

yumaworks-system.yang

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

yumaworks-system-dev.yang

YANG System deviations to identify currently unimplemented portions

yumaworks-term-msg.yang

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

yumaworks-yangpush-dev.yang

YANG Push deviations to identify currently unimplemented portions

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

Optional YANG Modules

Module

Description

Status

ietf-restconf-monitoring.yang

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

current

yuma-arp.yang

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

obsolete

yuma-proc.yang

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

obsolete

yuma-interfaces.yang

Yuma interfaces table. Build variable: WITH_YUMA_INTERFACES=1.

obsolete

yumaworks-schema-mount.yang

Contains the sm-config Structure for Schema Mount configuration. Build variable: WITH_SCHEMA_MOUNT=1:

current

yumaworks-server.yang

Allows server CLI parameters to be edited at run-time

current

yumaworks-yang-cbor.yang

Allows client to retrieve Binary Push configuration. Build variables: WITH_YANG_CBOR=1 and WITH_YANG_PUSH=1.

current

Notification Summary

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

CLI Parameters for Notifications

Parameter

Description

--eventlog-size

Size of the replay buffer for the NETCONF event stream

--event-stream

Configure a notification event stream

--event-stream-map

Configure a module to event stream mapping

--idle-timeout

Has no affect if notification delivery is active

--log-event-drops

Report dropped notifications in the server log

--max-burst

Control number of notifications sent at once to a receiver

--max-chunk-size

Control size of message chunks sent to the receiver

--system-notifications

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

--with-notifications

Must be set to true to enable notification delivery

--with-term-msg

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

--with-yuma-system

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

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

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

Module

Event Type

Description

nc-notifications

<replayComplete> Event

Notification replay has ended

nc-notifications

<notificationComplete> Event

Notification delivery has ended

ietf-yang-library

<yang-library-change> Event and <yang-library-update> Event

Set of modules or submodules in the YANG Library has changed

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

Module

Event Type

Description

ietf-netconf-notifications

<netconf-session-start> Event

NETCONF session has started

ietf-netconf-notifications

<netconf-session-end> Event

NETCONF session has ended

ietf-netconf-notifications

<netconf-config-change> Event

<running> configuration has changed

ietf-netconf-notifications

<netconf-capability-change> Event

Server capabilities have changed

ietf-netconf-notifications

<netconf-confirmed-commit> Event

Confirmed commit procedure event

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

Module

Event Type

Description

yuma-system

<sysStartup>

server startup event

yuma-system

<sysSessionStart>

NETCONF session has started

yuma-system

<sysSessionEnd>

NETCONF session has ended

yuma-system

<sysConfigChange>

<running> configuration has changed

yuma-system

<sysCapabilityChange>

Server capabilities have changed

yuma-system

<sysConfirmedCommit>

Confirmed commit procedure event

Pre-loaded Notifications if yang-push bundle enabled

Module

Event Type

Description

ietf-subscribed-notifications

<replay-completed> Event

subscription replay complete

ietf-subscribed-notifications

<subscription-modified> Event

subscription configuration modified

ietf-subscribed-notifications

<subscription-started> Event

configured subscription started or reset

ietf-subscribed-notifications

<subscription-terminated> Event

subscription terminated

ietf-yang-push

<push-update> Event

YANG Push Complete Update

ietf-yang-push

<push-change-update> Event

YANG Push Patch Update

Operation Summary

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

Pre-loaded Operations

Module

Operation

Description

none

<action>

Invoke a YANG 1.1 action defined in RFC 7950 Section 7.15

yumaworks-system.yang

<backup>

Backup the running configuration to a file

ietf-netconf.yang

<cancel-commit>

Cancel a confirmed-commit operation

yumaworks-system.yang

<cancel-subscription>

Cancel a notification subscription

yumaworks-event-stream.yang

<clear-eventlog>

Clear the replay buffer for an event stream

ietf-netconf.yang

<close-session>

Terminate the current session

ietf-netconf.yang

<commit>

Activate edits in <candidate>

yumaworks-compare.yang

<compare-config>

Compare configurations

ietf-netconf.yang

<copy-config>

Copy an entire configuration

notifications.yang

<create-subscription>

Start receiving notifications

yumaworks-system.yang

<delete-backup>

Delete a backup configuration file

ietf-netconf.yang

<delete-config>

Delete a configuration

ietf-subscribed-notifications.yang

<delete-subscription>

Delete a notification subscription by the owner session

ietf-netconf.yang

<discard-changes>

Discard edits in <candidate>

ietf-netconf.yang

<edit-config>

Edit the target configuration datastore

ietf-netconf-nmda.yang

<edit-data>

Edit the target configuration datastore

ietf-subscribed-notifications.yang

<establish-subscription>

Start a notification subscription

ietf-factory-default.yang

<factory-reset>

Start a full factory reset

ietf-netconf.yang

<get>

Retrieve <running> or state data

ietf-netconf.yang

<get-config>

Retrieve all or part of a configuration

ietf-netconf-nmda.yang

<get-data>

Retrieve data from an NMDA datastore

yumaworks-getbulk.yang

<get-bulk>

Retrieve N list entries at a time

yumaworks-system.yang

<get-ha-status>

Retrieve YP-HA status information

yumaworks-system.yang

<get-module-tags>

Retrieve the installed module-tags

yuma-mysession.yang

<get-my-session>

Retrieve session customization parameters

ietf-netconf-monitoring.yang

<get-schema>

Retrieve a YANG or YIN module definition file

yumaworks-system.yang

<get-server-version>

Retrieve the server version and build-date

yumaworks-sm-yanglib.yang

<get-sm-yanglib>

Retrieve the Schema Mount YANG Library information

ietf-netconf.yang

<kill-session>

Terminate a NETCONF session

ietf-subscribed-notifications.yang

<kill-subscription>

Delete a notification subscription by any session

yuma-system.yang

<load>

Load a YANG module and its SIL code [DEPRECATED]

yumaworks-system.yang

<load>

Load a YANG module and its SIL code

yumaworks-system.yang

<load-bundle>

Load a SIL bundle (SIL code + modules

yuma-netconf.yang

<load-config>

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

ietf-netconf.yang

<lock>

Lock a database

yumaworks-lock.yang

<lock-all>

Lock all configuration databases at once

ietf-subscribed-notifications.yang

<modify-subscription>

Modify a notification subscription

yuma-system.yang

<no-op>

No operation. [DEPRECATED]

ietf-netconf-partial-lock.yang

<partial-lock>

Lock part of the <running> database

ietf-netconf-partial-lock

<partial-unlock>

Unlock part of the <running> database

yumaworks-system.yang

<protocol-control>

Enable or disable client protocol sessions

yumaworks-system.yang

<refresh-backup-dir>

Refresh the backup-files monitoring data

yumaworks-internal.yang

<replay-config>

Internal RPC operation for configuration datastore synchronization

yumaworks-server.yang

<reload-netconf-tls-keypair>

Update the NETCONF over TLS server certificate and key at run-time

yuma-system.yang

<restart>

Restart the server. [DEPRECATED]

yumaworks-system.yang

<restore>

Restore the <running> database from a backup

ietf-yang-push.yang

<resync-subscription>

Re-synchronize a YANG Push notification subscription

yuma-system.yang

<set-log-level>

Set the logging verbosity level [DEPRECATED]

yumaworks-system.yang

<set-log-level>

Set the logging verbosity level

yuma-mysession.yang

<set-my-session>

Set the session customization parameters

yuma-system.yang

<shutdown>

Shutdown the server [DEPRECATED]

yumaworks-system.yang

<unload>

Unload a YANG module and its SIL code

yumaworks-system.yang

<unload-bundle>

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

ietf-netconf.yang

<unlock>

Unlock a database

yumaworks-lock.yang

<unlock-all>

Unlock all configuration databases at once

ietf-netconf.yang

<validate>

Validate a database

netconfd-pro Configuration Parameter List

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

netconfd-pro CLI Parameters

Parameter

Description

--access-control

Specifies how access control will be enforced

--allow-leaflist-delete-all

Allow delete-all operations on leaf-list objects

--allow-list-delete-all

Allow delete-all operations on list objects

--allowed-user

Limits sessions to specified user names

--alt-names

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

--annotation

Specifies a YANG module to load as an annotations module

--audit-log

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

--no-audit-log

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

--audit-log-append

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

--audit-log-candidate

Record transactions on the candidate datastore or not

--audit-log-console-level

Minimum debug level to generate console audit log messages

--audit-log-events

Select which events are recorded in the audit log

--audit-log-level

Minimum debug level to generate audit log messages

--audit-log-localtime

Modify the audit log to include timestamps in the local time zone

--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 Call Home 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 Call Home server before giving up.

--callhome-server

Specifies a NETCONF over SSH Call Home server that this server should attempt to initiate a Call Home 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 Call Home 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

--create-empty-npcontainers-ro

Specifies that empty NP containers with read-only children 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

--disable-imported-ok

Do not add top-level data nodes from imported modules

--disabled-protocols

Disabled client protocols ready to enable at run-time

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

--highres-event-time

Include a microseconds field in the notification 'eventTime' leaf

--home

Overrides the $HOME environment variable

--idle-timeout

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

--import-version-bestmatch

Enable import version best match feature

--indent

Specifies the indent count to use when writing data

--insecure-ok

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

--library-mode

Run the server in YANG library mode

--loadpath

Sets the module load path

--log

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

--log-append

Controls whether a log file will be reused or overwritten.

--log-backtrace

Append stack trace information to log messages.

--log-backtrace-detail

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

--log-backtrace-level

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

--log-backtrace-stream

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

--log-console

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

--log-event-drops

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

--log-header

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

--log-highres-datetime

Include a microseconds field in the log timestamps.

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

Control size of message chunks sent to the receiver

--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-lock-hold-time

Specifies the maximum number of seconds a session can hold a global lock

--max-per-user-sessions

Specifies the maximum number of concurrent sessions allowed for one user

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

--max-user-sessions

Specifies the maximum number of concurrent sessions allowed for all users

--message-indent

Specifies the amount to indent in protocol messages

--modpath

Sets the module search path

--module

Specifies one or more YANG modules to load upon startup

--module-tagmap

Specifies a module name to module-tag mapping

--netconf-capability

Specifies a NETCONF capability URI to add to the server

--netconf-tls-address

Specifies the IP address to listen for NETCONF over TLS sessions

--netconf-tls-certificate

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

--netconf-tls-key

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

--netconf-tls-port

Specifies the TCP port to list for NETCONF over TLS sessions

--netconf-tls-trust-store

Specifies the trust store file or directory for NETCONF over TLS

--no-config

If present, ignore the default configuration file

--no-log

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

--no-nvstore

Disable internal NV-load and NV-store operations

--no-startup

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

--no-watcher

Disable the ypwatcher program

--port

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

--protocols

Specifies which NETCONF protocol versions to enable

--push-max-operational

Specifies the maximum number of on-change push subscriptions

--push-max-periodic

Specifies the maximum number of periodic push subscriptions

--push-min-dampening

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

--push-min-period

Specifies the minimum value for the 'period' parameter

--push-simop-enabled

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

--push-simop-patch-update

Specifies the simulated on-change push subscription report type

--push-simop-period

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

--remove-schema-aug-leafs

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

--restconf-capability

Specifies a RESTCONF capability URI to add to the server

--restconf-default-encoding

Specifies the default response message encoding for RESTCONF

--restconf-server-url

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

--restconf-strict-headers

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

--return-empty-npcontainers

Specifies that empty NP containers should be returned or not

--return-error-with-data

Controls whether "<rpc-error>" nodes will be returned in RPC output for retrieval operations

--return-status

Specifies how the server will return a status code upon exit

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

--server-root

String identifying the server root when running in Multi-Instance Mode

--session-sync-mutex

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

--sil-cc-callback-all

Specifies that the CC callbacks should be invoked for all edit operations. (See Using Commit Completeness Callbacks)

--sil-delete-children-first

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

--sil-invoke-false-when-deletes

Specifies whether SIL callbacks are invoked for false-when auto-deletion.

--sil-invoke-for-defaults

Specifies whether SIL callbacks are invoked for 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-global-edit-validate

Prevents the server from invoking the Global EDIT callback during the Validate Phase.

--sil-skip-global-edit-apply

Prevents the server from invoking the Global EDIT callback during the Apply Phase.

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

--sm-config

Specifies the XML or JSON file to read which contains the configuration data needed to create desired mount-points.

--sm-config-encoding

Specifies the Schema Mount Config file encoding. Based on this encoding the server will parse the config file accordingly.

--socket-address

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

--socket-port

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

--socket-type

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

--startup

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

--startup-error

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

--startup-factory-file

Specifies the YANG configuration to use as the factory default config

--startup-prune-ok

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

--startup-skip-validation

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

--subdirs

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

--subsys-timeout

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

--superuser

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

--system-notifications

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

--system-sort-type

Specifies default sort type for system ordered lists and leaf-lists

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

--tcp-connect-timeout

The number of seconds to wait for the TCP connect function to finish

--tls-autosan-mode

Automatically use a valid Subject Alternate Name as the username

--tls-cipherlist

Specifies advanced OpenSSL cipher configuration settings.

--tls-common-auth

Specifies TLS Common Authentication should be used instead of Mutual Authentication.

--tls-crl-missing-ok

Specifies whether missing CRL Distribution Point is an error

--tls-crl-mode

Specifies how Certificate Revocation List processing is done

--tls-debug

Enable extended NETCONF over TLS logging information

--tls-deprecated-ok

Allow deprecated versions of TLS to be used

--tls-v1.3-only

Require TLS version 1.3 to be used for NETCONF over TLS sessions

--trim-whitespace

Specifies if leading and trailing XML whitespace should be trimmed

--usexmlorder

Forces strict YANG XML ordering to be enforced

--user-parm

Pass vendor-defined parameter string to instrumentation

--version

Prints the program version string and exits

--wait-datastore-ready

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

--warn-error

Treat all warnings as errors

--warn-idlen

Controls how identifier lengths are checked

--warn-linelen

Controls how line lengths are checked

--warn-off

Suppresses the specified warning number

--warn-off-yang

Suppresses all YANG warnings

--warn-up

Elevates the specified warning number to an error

--watcher-interval

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

--wildcard-keys

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

--with-callhome

Enable or disable the IETF Call Home 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-confirmed-commit

Enable or disable the :confirmed-commit capability URI

--with-db-lock

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

--with-error-number

Enable or disable the <error-number> leaf in <error-info> data

--with-factory-datastore

Enable or disable the IETF factory-default Support

--with-fsync

Enable or disable flushing data to disk when saving startup config

--with-gnmi

Enable or disable the gNMI protocol

--with-grpc

Enable or disable the gRPC protocol

--with-maintenance-mode

Enable or disable allowing maintenance mode to be used

--with-modtags

Enable or disable module-tags feature

--with-netconf

Enable or disable the NETCONF over SSH protocol

--with-netconf-tls

Enable or disable the NETCONF over TLS protocol

--with-new-notifs

Enable RFC 8639 Notifications even if 'bundle yang-push' not used

--with-new-yanglib

Enable RFC 8525 YANG Library even if NMDA not used

--with-nmda

Enable or disable NMDA support

--with-notifications

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

--with-ocpattern

Controls whether OpenConfig pattern syntax will be checked

--with-regex-filter

Enable or disable the Regex Filter feature

--with-restconf

Enable or disable the RESTCONF protocol

--with-rollback-on-error

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

--with-schema-mount

Enable or disable YANG Schema Mount support

--with-snmp

Enable or disable SNMP protocol support

--with-startup

Enable or disable the <startup> database

--with-support-save

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

--with-term-msg

Enable <term-msg> notification

--with-url

Enable or disable the :url capability

--with-url-ftp

Enable or disable FTP scheme in <url> parameter

--with-url-tftp

Enable or disable TFTP scheme in <url> parameter

--with-validate

Enable or disable the :validate capability

--with-warnings

Enable or disable the error-severity field set to warning

--with-yang-api

Enable or disable the YANG-API protocol

--with-yanglib-augmentedby

Enable or disable the ietf-yang-library-augmentedby.yang YANG module

--with-yang-cbor

Enable or disable the YANG/CBOR message encoding

--with-yang-metadata

Enable or disable the ietf-yang-metadata.yang module

--with-yang-patch-running

Enable or disable YANG Patch if target=running

--with-yang-push2

Enable YANG Push 2 features

--with-yang11-hello

Enable or disable strict YANG 1.1 <hello> message

--with-yp-coap

Enable the YP-COAP protocol

--with-yp-coap-dtls

Enable the YP-COAP over DTLS protocol

--with-yp-shell

Enable or disable the YP-SHELL protocol

--with-yuma-system

Enable or disable the yuma-system.yang module

--with-yuma-time-filter

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

--with-yumaworks-callhome

Enable or disable the yumaworks-callhome.yang module

--with-yumaworks-cert-usermap

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

--with-yumaworks-config-change

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

--with-yumaworks-event-filter

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

--with-yumaworks-event-stream

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

--with-yumaworks-getbulk

Enable or disable the yumaworks-getbulk.yang module

--with-yumaworks-ids

Enable or disable the yumaworks-ids.yang module

--with-yumaworks-lock

Enable or disable the yumaworks-lock.yang module

--with-yumaworks-sm-yanglib

Enable or disable the yumaworks-sm-yanglib.yang module

--with-yumaworks-system

Enable or disable the yumaworks-system.yang module

--with-yumaworks-templates

Enable or disable the yumaworks-templates.yang module

--yang-sid-mode

Select the YANG/CBOR SID assignment mode

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

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

--yumapro-home

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

Editing CLI Parameters at Run-Time

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

netconfd-pro {

  module yumaworks-server

}

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

> merge /server/max-sessions value=10

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

  • allowed-user

  • eventlog-size

  • hello-timeout:

  • idle-timeout

  • log-level

  • max-burst

  • max-cli-sessions: affects new sessions only

  • max-getbulk

  • max-sessions: affects new sessions only

  • subsys-timeout

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

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

  • The server has write permissions to rewrite the configuration file

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

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

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

Using logrotate to Manage Log Files

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

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

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

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

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

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

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

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

Maintenance Mode

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

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

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

Disabling YumaWorks YANG Modules

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

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

Parameter

Module

Description

--hide-module

any

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

--with-support-save

yumaworks-support-save.yang

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

--with-term-msg

yumaworks-term-msg.yang

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

--with-yuma-system
yuma-system.yang
yuma-app-common.yang
yuma-types.yang
yuma-ncx.yang

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

--with-yuma-time-filter

yuma-time-filter.yang

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

--with-yumaworks-callhome

yumaworks-callhome.yang

Run-time configuration or NETCONF Call Home connections.

--with-yumaworks-cert-usermap

yumaworks-cert-usermap.yang

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

--with-yumaworks-config-change

yumaworks-config-change.yang

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

--with-yumaworks-event-filter
yumaworks-event-filter.yang
yuma-types.yang
yuma-ncx.yang

<event-filters> container to drop specific event types

--with-yumaworks-event-stream
yumaworks-event-stream.yang
yuma-ncx.yang

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

--with-yumaworks-getbulk
yumaworks-getbulk.yang
yumaworks-restconf.yang

<get-bulk> operation to retrieve YANG list entries

--with-yumaworks-ids

yumaworks-ids.yang

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

--with-yumaworks-sm-yanglib

yumaworks-sm-yanglib.yang

<get-sm-yanglib> operation to retrieve Schema Mount YANG library

--with-yumaworks-system
yumaworks-system.yang
yuma-app-common.yang
yuma-ncx.yang
yuma-types.yang
yumaworks-app-common.yang
yumaworks-restconf.yang

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

--with-yumaworks-templates

yumaworks-templates.yang

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

DB-Config-Lock Mode

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

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

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

The following DB-API messages are used:

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

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

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

Configuration edits by all clients are affected by this lock.

Deferred Configuration Load Mode

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

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

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

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

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

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

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

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

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