../_images/logo.png

../_images/netconfd_components.png

netconfd-pro Introduction

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

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

netconfd-pro Features

The netconfd-pro server has the following features:

  • Complete implementation of NETCONF versions 1.0 and 1.1

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

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

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

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

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

  • Supports the RESTCONF Protocol defined in RFC 8040

  • Supports the YANG Patch Media Type defined in RFC 8072

  • Supports the CallHome for NETCONF feature defined in RFC 8071

    • Supports CLI and YANG configuration of CallHome servers

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

  • Supports Notification Subscriptions defined in RFC 5277 and RFC 8639

  • Supports YANG 1.1 Nested Notification Messages defined in RFC 7950

  • Supports Notifications over NETCONF defined in RFC 8640

  • Supports YANG 1.1 Actions defined in RFC 7950

  • Supports YANG Push defined in RFC 8641

  • Supports Schema Mount defined in RFC 8528

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

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

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

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

  • Complete XML 1.0 implementation with full support for XML Namespaces

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

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

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

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

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

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

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

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

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

  • Automatic subtree and full XPath filtering

  • Automatic confirmed-commit and rollback procedures

  • Automatic database audit log and change notification support

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

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

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

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

  • Dynamic Subscriptions to Event Streams defined in RFC 8639

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

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

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

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

  • Full support for all YANG constructs, including deviations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • gNMI and gRPC Protocol support

  • Maintenance Mode support

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

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

  • Built-in support for OpenConfig YANG Extensions

    • openconfig-version

    • openconfig-hashed-value

    • regexp-posix

  • Runtime configuration of NETCONF over TLS Certificate to Name Mappings

  • Binary Push: CBOR Encoding of Notification Messages (RFC 9254)

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.

db-api-app

The db-api-app program provides examples for using the DB-API Subsystem. It is a sample YumaPro subsystem program to demonstrate how the DB-API and YControl libraries can be used within an application. The netconfd-pro and db-api-app programs must be built with the make flag WITH_YCONTROL=1.

The default send_edit function will probably fail unless the server is configured with the correct YANG modules. Rewrite the send_edit request with your own parameters in db_api_app/main.c

Note

This program is not intended to be used as a real application. It is only intended to be used to provide examples for the DB-API library functions.

SYNOPSIS

send_edit:

db-api-app [--subsys=<subsys-id>] [<logging-parameters>]

getconfig:

db-api-app [--subsys=<subsys-id>] [<logging-parameters>]
   --getconfig [--withdef] --filespec=/path/to/output.xml
   [--with-state] [--xpath-filter=xpath-expression]

Maintenance Mode:

db-api-app --enter

db-api-app --enter=N

db-api-app --exit

Log Level:

db-api-app --set-log-level=dlevel

Sub RPC:

db-api-app --subrpc=name --filespec=filename [--in-filespec=filename]
   [--user=string]

Common parameters:

db-api-app --subsys=string [--retry-limit=num]

USAGE

The db-api-app program does not use a YANG-based configuration file.

If db-api-app is called without any parameters, it will attempt to send a test edit to the server. The module "test" must be loaded into the server for this edit to succeed. This test module is usually installed as /usr/share/yumapro/modules/test/pass/test.yang.

db-api-app supports the following CLI parameters:

  • --count=N

    The --count parameter can be used to specify number of times an edit request will be sent to the server.

  • --db-lock-change-state-time=N

    This parameter can be used to change the default frequency of sending <db-lock> and <db-unlock> requests for --db-lock-test. Default value is 7 seconds.

  • --db-lock-test

    The --db-lock-test parameter can be used to start the DB-API in a special test mode. The server must be started with --with-db-lock=true flag. The server will send <db-lock> and <db-unlock> requests to the db-api subsystem.

  • --db-lock-start-wait-time=N

    This parameter can be used to change the default wait time before sending the first <db-lock> request to the server for --db-lock-test. Default value is 30 seconds.

  • --enter

    The --enter parameter will cause a <enter-maintmode> request to be sent to the server.

  • enter=N

    The --enter=N parameter will cause a <enter-maintmode> request to be sent to the server, with the <allowed> parameter set according to the value of N:

    0 = no bits set
    1 = allow client sessions for read operations that read
        datastores or operational data
    2 = allow client sessions for general operations that
        do not access any datastores
    3 = allow read and operation sessions
    
  • --exit

    The --exit parameter will cause a <exit-maintmode> request to be sent to the server.

  • --filespec=/path/to/output.xml

    The --filespec parameter is required if the --getconfig parameter is present or if the --subrpc parameter is present. This specifies the file location to save the response from the server.

  • --getconfig

    The --getconfig parameter will cause a <getconfig> request to be sent to the server.

  • --log-level

    The log-level setting for the application. Affects all usage of logging functions.

  • in-filespec=/path/to/output.xml

    The --in-filespec parameter is optional if the --subrpc parameter is present. This specifies the XML file location to read the RPC input in the same form as used in the <rpc> element for NETCONF.

  • retry-limit=num

    The --retry-limit parameter will cause the subsystem to terminate after the specified number of re-connect attempts. The default value is 5000 re-connect attempts. The parameter is a uint16 number between 1 and 65535.

  • --set-log-level=enum

    The --set-log-level parameter will cause a <set-log-level> request to be sent to the server. The enum string values are the same as the --log-level parameter.

  • --subrpc=string

    The --subrpc parameter is used to send an RPC request to the server. This parameter specifies the name of the RPC operation. If any input is needed then the --in-filespec parameter must be present. The --filespec parameter must be present and specifies the name of the file to store the RPC output from the server. The --user parameter can be used to specify a user name for the RPC operation.

  • --subsys-id=string

    The --subsys-id parameter keyword is optional. It specifies the subsystem identifier to use when registering with the netconfd-pro server. The default is 'subsys1' if no value is specified.

    Warning

    The server will not function correctly if multiple subsystems register with the same name. This parameter must be used if the system has more than one subsystem.

  • --user=string

    The --user parameter can be used if the --subrpc parameter is present. It specifies the username for access control purposes that should be used on the server for the RPC operation. If not present then the RPC operation will be invoked as the system user without any access control at all.

  • --withdef

    The --withdef parameter will cause a <getconfig> request to be sent to the server including the <withdef> parameter set to true. If it is missing, the default is not to request YANG defaults.

  • --with-state

    The --with-state parameter will cause a <getconfig> request to be sent to the server including the <with-state> parameter set to true. This will cause all non-configuration data nodes to be returned. If it is missing, the default is not to request these data nodes.

  • xpath-filter=string

    The --xpath-filter parameter is used to add an optional XPath filter to the retrieval operation. If present, only data nodes included in the node-set result for this expression will be returned. The default is to return all data nodes.

combo-app

This program provides an example for combining the DB-API Subsystem. and SIL-SA Subsystem in a single program. There will be a single subsystem with one subsys-id value. A YControl subsystem can register any number of services. The netconfd-pro and combo-app programs must be built with the make flag WITH_YCONTROL=1.

This is a sample YumaPro subsystem program to demonstrate how the SIL-SA, DB-API, and YControl libraries can be used together within an application. If the --getconfig and --filespec parameters are present then the <get-config> operation will be sent about once per second, which the sil-sa-app is also active and processing SIL-SA requests. Use control-C to exit the program.

Note

This program is not entirely intended to be used as a real application. The DB-API portion is for example purposes only. The SIL-SA portiona can be used as a real application without modification.

SYNOPSIS

combo-app [--subsys=<subsys-id>] [--library=name] [<logging-parameters>]
   --getconfig [--withdef] --filespec=/path/to/output.xml
   [--with-state] [--xpath-filter=xpath-expression] [--retry-limit=num]

USAGE

The combo-app program does not use a YANG-based configuration file.

If combo-app is called without any parameters, it will attempt to connect to the server to register the SIL-SA and DB-API subsystems.

combo-app supports the db-api-app and sil-sa-app CLI parameters. They are not duplicated here.

netconf-subsystem-pro

The netconf-subsystem-pro program is a thin-client application that is called by the OpenSSH server to access the netconfd server, when the 'netconf' subsystem is requested.

This program is mandatory to use if the NETCONF protocol is used at all by client programs. The yp-shell program requires NETCONF access to the server. This is not a user-modifiable program. It is a complete application needed for the server to operate.

SYNOPSIS

netconf-subsystem-pro

USAGE

The location of this program needs to be configured in the /etc/ssh/sshd_config file. The following configuration needs to be present:

Port 22
Port 830
Subsystem netconf /usr/sbin/netconf-subsystem-pro

The actual filespec in the last line will depend on the location that this program is installed. The default value is shown in the example above.

There are no program options or environment variables used by this program.

Refer to the YumaPro Installation Guide for complete details on setting up the netconfd-pro server.

restconf

The restconf program is an HTTP/REST thin client application that is called by the FastCGI module in the WEB server to start a single RESTCONF request session for the specified user.

This program is mandatory to use if the RESTCONF protocol is used at all by client programs. This is not a user-modifiable program. It is a complete application needed for the server to operate. The netconfd-pro and restconf programs must be built with the make flag WITH_RESTCONF=1.

The location of this program needs to be configured in the WEB server config file. Refer to the RESTCONF Installation section for details. The default installation directory is /var/www/yang-api. The /var/www/yang-api/restconf program may need to be relocated to a different directory specific to the WEB server CGI-BIN configuration.

The '{+restconf}' entry point is configurable with the --entry-point CLI parameter. The default entry point is /restconf. Refer to RFC 8040 for details on the RESTCONF standard.

SYNOPSIS

restconf

USAGE

There are no program options or environment variables used by this program.

sil-sa-app

The sil-sa-app program provides a complete functioning application for implementing YANG object callback functions in a subsystem. It provides complete functionaility for the SIL-SA Subsystem. The netconfd-pro and sil-sa-app programs must be built with the make flag WITH_YCONTROL=1.

Note

This program is a complete application. The SIL-SA functionality will only be supported if this subsystem application is used correctly.

SYNOPSIS

sil-sa-app [--subsys=<subsys-id>] [--library=name]
    [<logging-parameters>] [--retry-limit=num]

USAGE

The sil-sa-app program does not use a YANG-based configuration file.

If sil-sa-app is called without any parameters, it will attempt to connect to the server with default settings (e.g. subsys-id=subsys1).

sil-sa-app supports the following CLI parameters:

  • --address=string

    The --address parameter is optional. It represents the IP address of the main server that will be used for the session. The default is localhost.

  • --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. This option can be used multiple 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 'runpath' (e.g. /usr/lib/yumapro directory) then it will be skipped by the subsystem.

    Example:
    
    --library=foo  (selects libfoo_sa.so)
    
  • --log-level=enum

    The --log-level, --log, and other logging parameters are also supported.

  • --port=uint16

    The --port parameter is optional. It represents the TCP port number of the main server that will be used for the session. The default is the local system, determined by the local netconf-subsystem-pro.

  • --retry-limit=num

    The --retry-limit parameter will cause the subsystem to terminate after the specified number of re-connect attempts. The default value is 5000 re-connect attempts. The parameter is a uint16 number between 1 and 65535.

  • --subsys-id=string

    The --subsys-id parameter keyword is optional. It specifies the subsystem identifier to use when registering with the netconfd-pro server. The default is 'subsys1' if no value is specified.

ypgrpc-go-app

The ypgrpc-go-app program is is a YControl subsystem that communicates to the netconfd-pro server. Also it is a gRPC server that communicates to the gRPC clients.

Refer to the YumaPro gRPC Manual for details about this program.

USAGE

The ypgrpc-go-app program does not use a YANG-based configuration file.

ypgrpc-go-app supports the following CLI parameters:

  • --fileloc-fhs=boolean

    The --fileloc-fhs parameter is supported.

  • --insecure=boolean

    The --insecure parameter specifies whether the ypgrpc-go-app should skip TLS validation or should try to velidate CA certificates. If false then the ypgrpc-go-app will skip all security validation.

  • --log=filespec

    The --log and --log-level parameters are supported. There are 4 settings that can be used:

    error:  print errors
    warn:   print warnings
    info:   print generally interesting trace info
    debug:  print verbose debugging trace info
    
  • --port=uint16

    The --port parameter specifies Port value to use for gRPC server connections. The default is '50830' if no value is specified.

  • --protopath=string

    The --protopath parameter specifies directory search path for PROTO files. E.g., --protopath=/some/path --protopath=$HOME/proto

  • --proto=string

    The --proto parameter specifies the PROTO source proto file for the ypgrpc-go-app application to load and use.

  • --server-address=string

    The --server-address parameter specifies the netconfd-pro server address. This is the address that the ypgrpc-go-app will use to contact the netconfd-pro server. By default the address is the local host: 127.0.0.1.

  • --Bsubsys-id=string

    The --subsys-id parameter specifies the subsystem identifier to use when registering with the netconfd-pro server. The default is 'example-grpc' if no value is specified.

ypgnmi-app

The ypgnmi-app program is a YControl subsystem that communicates to the netconfd-pro server. It also is a gNMI server that communicates to the gNMI clients. The ypgnmi-app is responsible for encoding conversion between gNMI gRPC to XML/JSON that are sent to the netconfd-pro server and vise versa.

Refer to the YumaPro gNMI Manual for details about this program.

USAGE

The ypgnmi-app program does not use a YANG-based configuration file.

ypgnmi-app supports the following CLI parameters:

  • --bind-address=string

    The --bind-address parameter specifies the gNMI server binding. This is the address that the gNMI client will use top contact the gNMI server. By default the address is the local host and default port is 10161.

  • --ca=filespec

    The --ca parameter specifies the gNMI server CA certificate file. The path to the CA certificate should be absolute.

  • --cert=filespec

    The --cert parameter specifies the gNMI server certificate file. The path to the certificate should be absolute.

  • --fileloc-fhs=boolean

    The --fileloc-fhs parameter is supported.

  • --key=filespec

    The --key parameter specifies the gNMI server private key file. The path to the key should be absolute.

  • --log=filespec

    The --log and --log-level parameters are supported. There are 4 settings that can be used:

    error:  print errors
    warn:   print warnings
    info:   print generally interesting trace info
    debug:  print verbose debugging trace info
    
  • --server=string

    The --server parameter specifies the netconfd-pro server IP address. The default is '127.0.0.1' if no value is specified.

  • --server-id=string

    The --server-id parameter specifies the server identifier to use when registering with the netconfd-pro server. The default is 'server1' if no value is specified.

  • --service-id=string

    The --service-id parameter specifies the service identifier to use when registering with the netconfd-pro server. The default is 'yp-gnmi' if no value is specified.

  • --subsys-id=string

    The --subsys-id parameter specifies the subsystem identifier to use when registering with the netconfd-pro server. The default is 'yp-gnmi' if no value is specified.

yp-ha-app

The yp-ha-app program is a sample YumaPro subsystem program to demonstrate how the DB-API service can be used to send YumaPro High Availability <yp-ha-mode> messages to the local server. The netconfd-pro and yp-ha-app programs must be built with the make flag WITH_YCONTROL=1.

Note

This program is a complete application that can be used to set the YP-HA role for the local server.

SYNOPSIS

yp-ha-app --go-active
   [--subsys=<subsys-id>] [<logging-parameters>]

yp-ha-app --go-standby=new-active
   [--subsys=<subsys-id>] [<logging-parameters>]

yp-ha-app --go-none
   [--subsys=<subsys-id>] [<logging-parameters>]

USAGE

The yp-ha-app program does not use a YANG-based configuration file.

Exactly 1 of the following 3 CLI parameters must be present.

  • --go-active

  • --go-standby

  • --go-none

yp-ha-app supports the following CLI parameters:

  • --go-active

    The --go-active command is used to tell the local server to switch to YP-HA Active mode.

  • --go-standby=string

    The --go-standby=new-active command is used to tell the local server to switch to YP-HA Standby mode. The "new-active" parameter is the name of the YP-HA server that should be used as the new YP-HA Active server. Only 'superuser' management sessions are available in this mode.

  • --go-none

    The --go-none command is used to tell the local server to go offline and leave its YP-HA role. In this mode the server will wait for a new HA role to be set. Only 'superuser' management sessions are available in this mode.

  • subsys-id=string

    The --subsys-id parameter keyword is optional. It specifies the subsystem identifier to use when registering with the netconfd-pro server. The default is 'subsys1' if no value is specified.

  • log-level=enum

    The --log and --log-level parameters are supported.

RETURN VALUE

A return status from the application or the server is returned that represents a status code, found in ncx/status_enum.h. The value 0 (NO_ERR) indicates the server accepted the HA command. A non-zero value indicates that the application or the server rejected the request, or it failed immediately.

yp-shell

The yp-shell program is a CLI client application that is called by the login process server to start a shell for the specified user. It is usually installed as the login shell for the local user. Refer to the yp-shell – adding a CLI section for details on installing the yp-shell program. The netconfd-pro and yp-shell programs must be built with the make flag WITH_CLI=1.

The functionality in yp-shell is a subset of the features described in the YumaPro yangcli-pro Manual.

The yp-shell program is a NETCONF client that only connects 1 session to the local server. A command line interface to the server operations is provided. If the session terminates the program will exit.

Note

This program is a complete application that is required if the server CLI functionality is used.

USAGE

This program uses the 'yangcli-pro' configuration file if it is found. The default location is /etc/yumapro/yangcli-pro.conf.

Many of the yangcli-pro features are disabled in yp-shell. A subset of the CLI parameters found in the yangcli-pro CLI Reference are supported. The section for each parameter should identify if yp-shell supports the parameter.

Setting the Server Profile

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Loading YANG Modules

Loading Modules at Boot-Time

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

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

Loading Modules at Run-Time

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

Loading Bundles at Boot-Time

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

Loading Bundles at Run-Time

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

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

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

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

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

Unloading YANG Modules

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

Modules imported by the module being unloaded are not unloaded.

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

Modules imported by the bundle are unloaded.

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

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

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

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

Starting netconfd-pro

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

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

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

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

The netconfd-pro program can be invoked several ways:

  • To get the current version and exit:

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

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

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

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

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

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

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

netconfd-pro --fileloc-fhs=true

Starting SIL-SA Subsystems with sil-sa-app

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

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

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

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

  • --address=ip-address

    • The IP address of the main server.

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

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

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

  • --library=string

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

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

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

    • Example:

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

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

  • --log=filespec

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

  • --port=uint16

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

    • The default is 2023.

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

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

  • --subsys-id=string

    • The subsystem identifier to use.

    • The default is subsys1.

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

The SIL-SA libraries loaded depends on 2 factors:

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

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

Example: Start the server with a non-default socket

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

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

Example 2: Start 2 subsystems on the same host

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

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

Stopping netconfd-pro

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

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

Signal Handling

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

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

Signals Recognized by netconfd-pro

Signal

Number

Description

SIGHUP (Hangup)

1

Restart the server.

SIGINT (Control-C)

2

Shutdown the server.

SIGQUIT

3

Shutdown the server.

SIGILL

4

Shutdown the server.

SIGTRAP

5

Shutdown the server.

SIGABRT

6

Shutdown the server.

SIGKILL

9

Kill the server process (No proper cleanup!)

SEGUSR1

10

Reload the server (Does a restart)

SEGUSR2

12

Logrotate (reopen log files)

SIGPIPE

13

Handle I/O connection error.

SIGTERM

15

Shutdown the server.

SIGVTALRM

26

Internal threads kill signal

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

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

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

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

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

Starting netconfd-pro with ypwatcher program

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

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

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

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

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

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

netconfd-pro --no-watcher

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

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

netconfd-pro --watcher-interval=10

Signal Handling with ypwatcher program

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

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

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

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

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

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

Signals Recognized by ypwatcher

Signal

Number

Description

SIGBUS

7

Bus error.

SIGFPE

8

Floating Point exception.

SIGKILL

9

Kill

SIGSEGV

11

Invalid memory reference

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

netconfd-pro Error Handling

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

The following CLI parameters affect error handling:

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

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

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

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

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

  • Incoming PDU validation

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

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

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

  • Server instrumentation PDU validation

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

  • Database validation

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

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

    • The specific conditions checked automatically are:

      • referential integrity condition test failed (must)

      • missing leaf (mandatory)

      • missing choice (mandatory)

      • extra container or leaf

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

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

      • instance not unique (unique)

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

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

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

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

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

  • Server instrumentation database validation and activation

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

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

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

Module Summary

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

Pre-loaded YANG Modules

Module

Description

ietf-datastores.yang

NMDA datastore meta-data

ietf-inet-types.yang

standard data types

ietf-netconf-acm.yang

standard NETCONF access control model

ietf-netconf-monitoring.yang

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

ietf-netconf-nmda.yang

NMDA <get-data> operation for NETCONF

ietf-netconf-notifications.yang

standard NETCONF notifications for system events

ietf-netconf-partial-lock.yang

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

ietf-netconf-with-defaults.yang

<with-defaults> extension

ietf-origin.yang

NMDA <operational> origin meta-data

ietf-subscribed-notifications.yang

Dynamic Notification Subscriptions from RFC 8639

ietf-x509-cert-to-name.yang

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

ietf-yang-library.yang

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

ietf-yang-push.yang

Subscriptions to YANG Datastores from RFC 8641

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 CallHome server parameters

yumaworks-cert-usermap.yang

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

yumaworks-config-change.yang

Add edit data to the netconf-config-change notification

yumaworks-event-filter.yang

Event filters to suppress generation of notifications for the specified events

yumaworks-event-stream.yang

NETCONF Event stream configuration

yumaworks-extensions.yang

YANG extensions for meta-data data tagging

yumaworks-getbulk.yang

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

yumaworks-ids.yang

Session type extensions for the standard monitoring module

yumaworks-restconf-commit.yang

Extensions to add confirmed-commit procedure to RESTCONF

yumaworks-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 back/restore, unload, etc.

yumaworks-term-msg.yang

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

yumaworks-yangpush-dev.yang

YANG Push deviations to identify currently unimplemented portions

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

Optional YANG Modules

Module

Description

Status

ietf-restconf-monitoring.yang

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

current

yuma-arp.yang

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

obsolete

yuma-proc.yang

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

obsolete

yuma-interfaces.yang

Yuma interfaces table. Build variable: WITH_YUMA_INTERFACES=1.

obsolete

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

--system-notifications

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

--with-notifications

Must be set to true to enable notification delivery

--with-term-msg

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

--with-yuma-system

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

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

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

Module

Event Type

Description

nc-notifications

<replayComplete> Event

Notification replay has ended

nc-notifications

<notificationComplete> Event

Notification delivery has ended

ietf-yang-library

<yang-library-change> Event

Set of modules or submodules in the YANG Library has changed

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

Module

Event Type

Description

ietf-netconf-notifications

<netconf-session-start> Event

NETCONF session has started

ietf-netconf-notifications

<netconf-session-end> Event

NETCONF session has ended

ietf-netconf-notifications

<netconf-config-change> Event

<running> configuration has changed

ietf-netconf-notifications

<netconf-capability-change> Event

Server capabilities have changed

ietf-netconf-notifications

<netconf-confirmed-commit> Event

Confirmed commit procedure event

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

Module

Event Type

Description

yuma-system

<sysStartup>

server startup event

yuma-system

<sysSessionStart>

NETCONF session has started

yuma-system

<sysSessionEnd>

NETCONF session has ended

yuma-system

<sysConfigChange>

<running> configuration has changed

yuma-system

<sysCapabilityChange>

Server capabilities have changed

yuma-system

<sysConfirmedCommit>

Confirmed commit procedure event

Pre-loaded Notifications if yang-push bundle enabled

Module

Event Type

Description

ietf-subscribed-notifications

<replay-completed> Event

subscription replay complete

ietf-subscribed-notifications

<subscription-modified> Event

subscription configuration modified

ietf-subscribed-notifications

<subscription-terminated> Event

subscription terminated

ietf-yang-push

<push-update> Event

YANG Push Complete Update

ietf-yang-push

<push-change-update> Event

YANG Push Patch Update

Operation Summary

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

Pre-loaded Operations

Module

Operation

Description

yumaworks-system.yang

<backup>

Backup the running configuration to a file

ietf-netconf.yang

<cancel-commit>

Cancel a confirmed-commit operation

yumaworks-system.yang

<cancel-subscription>

Cancel a notification subscription

yumaworks-event-stream.yang

<clear-eventlog>

Clear the replay buffer for an event stream

ietf-netconf.yang

<close-session>

Terminate the current session

ietf-netconf.yang

<commit>

Activate edits in <candidate>

ietf-netconf.yang

<copy-config>

Copy an entire configuration

notifications.yang

<create-subscription>

Start receiving notifications

yumaworks-system.yang

<delete-backup>

Delete a backup configuration file

ietf-netconf.yang

<delete-config>

Delete a configuration

ietf-subscribed-notifications.yang

<delete-subscription>

Delete a notification subscription by the owner session

ietf-netconf.yang

<discard-changes>

Discard edits in <candidate>

ietf-netconf.yang

<edit-config>

Edit the target configuration

ietf-subscribed-notifications.yang

<establish-subscription>

Start a notification subscription

ietf-netconf.yang

<get>

Retrieve <running> or state data

ietf-netconf.yang

<get-config>

Retrieve all or part of a configuration

ietf-netconf-nmda.yang

<get-data>

Retrieve data from an NMDA datastore

yumaworks-getbulk.yang

<get-bulk>

Retrieve N list entries at a time

yumaworks-system.yang

<get-ha-status>

Retrieve YP-HA status information

yumaworks-system.yang

<get-module-tags>

Retrieve the installed module-tags

yuma-mysession.yang

<get-my-session>

Retrieve session customization parameters

ietf-netconf-monitoring.yang

<get-schema>

Retrieve a YANG or YIN module definition file

yumaworks-system.yang

<get-server-version>

Retrieve the server version and build-date

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

ietf-subscribed-notifications.yang

<modify-subscription>

Modify a notification subscription

yuma-system.yang

<no-op>

No operation. [DEPRECATED]

ietf-netconf-partial-lock.yang

<partial-lock>

Lock part of the <running> database

ietf-netconf-partial-lock

<partial-unlock>

Unlock part of the <running> database

yumaworks-system.yang

<refresh-backup-dir>

Refresh the backup-files monitoring data

yumaworks-internal.yang

<replay-config>

Internal RPC operation for configuration datastore synchronization

yuma-system.yang

<restart>

Restart the server. [DEPRECATED]

yumaworks-system.yang

<restore>

Restore the <running> database from a backup

ietf-yang-push.yang

<resync-subscription>

Re-synchronize a YANG Push notification subscription

yuma-system.yang

<set-log-level>

Set the logging verbosity level [DEPRECATED]

yumaworks-system.yang

<set-log-level>

Set the logging verbosity level

yuma-mysession.yang

<set-my-session>

Set the session customization parameters

yuma-system.yang

<shutdown>

Shutdown the server [DEPRECATED]

yumaworks-system.yang

<unload>

Unload a YANG module and its SIL code

yumaworks-system.yang

<unload-bundle>

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

ietf-netconf.yang

<unlock>

Unlock a database

ietf-netconf.yang

<validate>

Validate a database

netconfd-pro Configuration Parameter List

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

netconfd-pro CLI Parameters

Parameter

Description

--access-control

Specifies how access control will be enforced

--allow-leaflist-delete-all

Allow delete-all operations on leaf-list objects

--allow-list-delete-all

Allow delete-all operations on list objects

--allowed-user

Limits sessions to specified user names

--alt-names

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

--annotation

Specifies a YANG module to load as an annotations module

--audit-log

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

--no-audit-log

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

--audit-log-append

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

--audit-log-candidate

Record transactions on the candidate datastore or not

--audit-log-console-level

Minimum debug level to generate console audit log messages

--audit-log-events

Select which events are recorded in the audit log

--audit-log-level

Minimum debug level to generate audit log messages

--autodelete-pdu-error

Treat false when-stmts in the edit PDU as errors

--binary-display-maxlen

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

--bundle

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

--callhome-reconnect

Specifies whether server will reconnect after client closes the session

--callhome-retry-interval

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

--callhome-retry-max

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

--callhome-server

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

--callhome-sshd-command

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

--callhome-sshd-config

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

--callhome-subsys-command

Specifies the command used in CallHome to invoke the netconf subsystem

--callhome-tls-server

Specifies a NETCONF over TLS CallHome server

--cert-default-user

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

--cert-usermap

Specifies a user-name to certificate mapping

--confdir

Specifies the directory for extra configuration parameter files

--config

Specifies the configuration file to use for parameters

--convert-subtree-filter

Convert subtree filters to XPath for internal processing

--create-empty-npcontainers

Specifies that empty NP containers should be created or not

--datapath

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

--db-lock-retry-interval

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

--db-lock-timeout

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

--default-style

Specifies the default <with-defaults> behavior

--delete-empty-npcontainers

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

--deviation

Species a YANG module to load as a deviations module

--errmsg

Specifies a language-specific error message

--errmsg-lang

Specifies the error-message language to use

--eventlog-size

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

--event-stream

Configure a notification event stream

--event-stream-map

Configure a module to event stream mapping

--factory-startup

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

--feature-disable

Leaf list of features to disable

--feature-enable

Specifies a feature that should be enabled

--feature-enable-default

Specifies if a feature should be enabled or disabled by default

--fileloc-fhs

Selects Filesystem Hierarchy Standard (FHS) directory locations

--ha-enabled

Enable or disable the YP-HA feature

--ha-initial-active

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

--ha-server

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

--ha-server-key

Unique string identifying the YP-HA server pool

--ha-sil-standby

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

--hello-timeout

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

--help

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

--hide-module

Hide the specified module from clients

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

Specifies the maximum number of concurrent CLI sessions allowed

--max-getbulk

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

--max-sessions

Specifies the maximum number of concurrent sessions allowed

--max-strlen

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

--message-indent

Specifies the amount to indent in protocol messages

--modpath

Sets the module search path

--module

Specifies one or more YANG modules to load upon startup

--module-tagmap

Specifies a module name to module-tag mapping

--netconf-capability

Specifies a NETCONF capability URI to add to the server

--netconf-tls-address

Specifies the IP address to listen for NETCONF over TLS sessions

--netconf-tls-certificate

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

--netconf-tls-key

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

--netconf-tls-port

Specifies the TCP port to list for NETCONF over TLS sessions

--netconf-tls-trust-store

Specifies the trust store file or directory for NETCONF over TLS

--no-config

If present, ignore the default configuration file

--no-log

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

--no-nvstore

Disable internal NV-load and NV-store operations

--no-startup

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

--no-watcher

Disable the ypwatcher program

--port

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

--protocols

Specifies which NETCONF protocol versions to enable

--push-max-operational

Specifies the maximum number of on-change push subscriptions

--push-max-periodic

Specifies the maximum number of periodic push subscriptions

--push-min-dampening

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

--push-min-period

Specifies the minimum value for the 'period' parameter

--push-simop-enabled

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

--push-simop-patch-update

Specifies the simulated on-change push subscription report type

--push-simop-period

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

--remove-schema-aug-leafs

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

--restconf-capability

Specifies a RESTCONF capability URI to add to the server

--restconf-default-encoding

Specifies the default response message encoding for RESTCONF

--restconf-server-url

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

--restconf-strict-headers

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

--runpath

Server instrumentation library (SIL) search path

--running-error

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

--save-owners

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

--server-id

String identifying the server in the YP-HA server pool

--session-sync-mutex

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

--sil-delete-children-first

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

--sil-invoke-for-defaults

Specifies whether SIL callbacks are invoked for loading defaults

--sil-missing-error

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

--sil-prio-reverse-for-deletes

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

--sil-root-check-first

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

--sil-skip-load

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

--sil-test-get-when

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

--sil-validate-candidate

Controls whether SIL callbacks will be done for the candidate datastore

--simple-json-names

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

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

Specifies advanced OpenSSL cipher configuration settings.

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

--trim-whitespace

Specifies if leading and trailing XML whitespace should be trimmed

--usexmlorder

Forces strict YANG XML ordering to be enforced

--version

Prints the program version string and exits

--wait-datastore-ready

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

--warn-error

Treat all warnings as errors

--warn-idlen

Controls how identifier lengths are checked

--warn-linelen

Controls how line lengths are checked

--warn-off

Suppresses the specified warning number

--warn-up

Elevates the specified warning number to an error

--watcher-interval

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

--wildcard-keys

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

--with-callhome

Enable or disable the IETF CallHome protocol

--with-canonical

Enable or disable automatic conversion to canonical data type format

--with-config-id

Enable or disable the :config-id capability URI

--with-db-lock

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

--with-gnmi

Enable or disable the gNMI protocol

--with-grpc

Enable or disable the gRPC protocol

--with-maintenance-mode

Enable or disable allowing maintenance mode to be used

--with-modtags

Enable or disable module-tags feature

--with-netconf

Enable or disable the NETCONF over SSH protocol

--with-netconf-tls

Enable or disable the NETCONF over TLS protocol

--with-nmda

Enable or disable NMDA support

--with-notifications

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

--with-ocpattern

Controls whether OpenConfig pattern syntax will be checked

--with-schema-mount

Enable or disable YANG Schema Mount support

--with-restconf

Enable or disable the RESTCONF protocol

--with-rollback-on-error

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

--with-startup

Enable or disable the <startup> database

--with-support-save

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

--with-term-msg

Enable <term-msg> notification

--with-url

Enable or disable the :url capability

--with-url-ftp

Enable or disable FTP scheme in <url> parameter

--with-url-tftp

Enable or disable TFTP scheme in <url> parameter

--with-validate

Enable or disable the :validate capability

--with-warnings

Enable or disable the error-severity field set to warning

--with-yang-api

Enable or disable the YANG-API protocol

--with-yp-coap

Enable the YP-COAP protocol

--with-yp-coap-dtls

Enable the YP-COAP over DTLS protocol

--with-yp-shell

Enable or disable the YP-SHELL protocol

--with-yuma-time-filter

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

--with-yuma-system

Enable or disable the yuma-system.yang module

--with-yumaworks-callhome

Enable or disable the yumaworks-callhome.yang module

--with-yumaworks-cert-usermap

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

--with-yumaworks-config-change

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

--with-yumaworks-event-filter

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

--with-yumaworks-event-stream

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

--with-yumaworks-getbulk

Enable or disable the yumaworks-getbulk.yang module

--with-yumaworks-ids

Enable or disable the yumaworks-ids.yang module

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

--yangapi-server-url

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

--yumapro-home

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

--yp-coap-address

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

--yp-coap-dtls-port

UDP port to use for YP-CoAP over DTLS protocol

--yp-coap-port

UDP port to use for YP-CoAP protocol

Editing CLI Parameters at Run-Time

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

netconfd-pro {

  module yumaworks-server

}

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

> merge /server/max-sessions value=10

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

  • allowed-user

  • eventlog-size

  • hello-timeout:

  • idle-timeout

  • log-level

  • max-burst

  • max-cli-sessions: affects new sessions only

  • max-getbulk

  • max-sessions: affects new sessions only

  • subsys-timeout

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

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

  • The server has write permissions to rewrite the configuration file

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

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

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

Using logrotate to Manage Log Files

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

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

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

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

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

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

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

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

Evaluation Version Restrictions

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

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

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

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

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

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

Maintenance Mode

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

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

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

Disabling YumaWorks YANG Modules

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

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

Parameter

Module

Description

--hide-module

any

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

--with-support-save

yumaworks-support-save.yang

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

--with-term-msg

yumaworks-term-msg.yang

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

--with-yuma-system

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

--with-yuma-time-filter

yuma-time-filter.yang

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

--with-yumaworks-callhome

yumaworks-callhome.yang

Run-time configuration or NETCONF CallHome connections.

--with-yumaworks-cert-usermap

yumaworks-cert-usermap.yang

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

--with-yumaworks-config-change

yumaworks-config-change.yang

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

--with-yumaworks-event-filter

<event-filters> container to drop specific event types

--with-yumaworks-event-stream

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

--with-yumaworks-getbulk

<get-bulk> operation to retrieve YANG list entries

--with-yumaworks-ids

yumaworks-ids.yang

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

--with-yumaworks-sm-yanglib

yumaworks-sm-yanglib.yang

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

--with-yumaworks-system

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

--with-yumaworks-templates

yumaworks-templates.yang

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

DB-Config-Lock Mode

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

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

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

The following DB-API messages are used:

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

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

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

Configuration edits by all clients are affected by this lock.

Deferred Configuration Load Mode

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

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

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

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

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

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

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

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

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