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 Call Home for NETCONF feature defined in RFC 8071
Supports CLI and YANG configuration of Call Home 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
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 northbound 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
Full support for RFC 7589 Client Identity certificate processing procedures
yumaworks-cert-usermap.yang uses the 'cert-to-name' grouping from ietf-x509-cert-to-name.yang (RFC 7407)
Binary Push: CBOR Encoding of Notification Messages (RFC 9254)
System Sorted Configuration
Global and Object Level Control of Automatic Sort Type
Multi-Instance Mode:
Run multiple instances of the netconfd-pro server and its components on the same host
Uses IP address and/or TCP port mapping to assign NETCONF over SSH connections to specific server instances
Uses a configured 'server root ID' to keep the files and AFLOCAL sockets separate for each server instance
Server Programs
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.
-
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.
--server-root=string
The --server-root parameter is required if the server is running in Multi-Instance Mode. This identifies the server instance that this program will attempt in its server connection.
--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 portion 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 functionality 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.
--server-root=string
The --server-root parameter is required if the server is running in Multi-Instance Mode. This identifies the server instance that this program will attempt in its server connection.
--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 validate 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.
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/yumaprodirectory. 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
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 |
|---|---|
NMDA datastore meta-data |
|
standard data types |
|
standard NETCONF access control model |
|
standard NETCONF monitoring, and the <get-schema> operation |
|
NMDA <get-data> operation for NETCONF |
|
standard NETCONF notifications for system events |
|
standard NETCONF <partial-lock> and <partial-unlock> operations |
|
<with-defaults> extension |
|
NMDA <operational> origin meta-data |
|
Dynamic Notification Subscriptions from RFC 8639 |
|
X.509 cert-to-name configuration used for NETCONF over TLS |
|
standard NETCONF YANG Module Library that represent the current set of modules and submodules. |
|
Subscriptions to YANG Datastores from RFC 8641 |
|
YANG Schema Mount from RFC 8528 |
|
standard data types |
|
standard replay notifications |
|
Server CLI parameters |
|
standard notification operations |
|
openconfig-extensions.yang |
Many OC extensions supported (used in other modules) |
Yuma NETCONF extensions |
|
Common CLI parameters |
|
Yuma common data types |
|
Get and Set session-specific parameters |
|
system monitoring, operations, and notifications. This module is deprecated. It is enabled by default, but can be removed using --with-yuma-system=false |
|
Get only if datastore changed since a specified timestamp |
|
Common definitions used by yumapro modules |
|
Extensions to add last-modified and etag attributes |
|
Runtime configuration of Call Home server parameters |
|
Add X.509 cert-to-name mapping configuration used for NETCONF over TLS |
|
Add edit data to the netconf-config-change notification |
|
Event filters to suppress generation of notifications for the specified events |
|
NETCONF Event stream configuration |
|
YANG extensions for meta-data data tagging |
|
NETCONF <get-bulk> operation to easily iterate through YANG lists |
|
Session type extensions for the standard monitoring module |
|
NETCONF <lock-all> and <unlock-all> operations to simplify datastore locking for editing |
|
Extensions to add confirmed-commit procedure to RESTCONF |
|
Contains the sm-config Structure for Schema Mount configuration |
|
Contains the <get-sm-yanglib> operation to retrieve Schema Mount YANG libray information |
|
Contains the <get-support-save> operation |
|
Extensions to ietf-netconf-monitoring, plus extra protocol operations for back/restore, unload, etc. |
|
<term-msg> Notification for yp-shell diagnostic messages |
|
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 |
|---|---|---|
Monitoring information for the RESTCONF protocol. Build variable: WITH_RESTCONF=1 |
current |
|
collection of YANG definitions for configuring and monitoring ARP. Build variable: WITH_YUMA_ARP=1 |
obsolete |
|
NETCONF /proc file system monitoring. Build variable: WITH_YUMA_PROC=1: |
obsolete |
|
Yuma interfaces table. Build variable: WITH_YUMA_INTERFACES=1. |
obsolete |
|
Contains the sm-config Structure for Schema Mount configuration. Build variable: WITH_SCHEMA_MOUNT=1: |
current |
|
Allows server CLI parameters to be edited at run-time |
current |
|
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 |
|---|---|
Size of the replay buffer for the NETCONF event stream |
|
Configure a notification event stream |
|
Configure a module to event stream mapping |
|
Has no affect if notification delivery is active |
|
Report dropped notifications in the server log |
|
Control number of notifications sent at once to a receiver |
|
Pick IETF or Yuma system notifications. Default is IETF. Yuma is deprecated and should not be used |
|
Must be set to true to enable notification delivery |
|
Must be set to true to enable <term-msg> event |
|
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 |
Notification replay has ended |
|
nc-notifications |
Notification delivery has ended |
|
ietf-yang-library |
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 has started |
|
ietf-netconf-notifications |
NETCONF session has ended |
|
ietf-netconf-notifications |
<running> configuration has changed |
|
ietf-netconf-notifications |
Server capabilities have changed |
|
ietf-netconf-notifications |
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 |
subscription replay complete |
|
ietf-subscribed-notifications |
subscription configuration modified |
|
ietf-subscribed-notifications |
subscription terminated |
|
ietf-yang-push |
YANG Push Complete Update |
|
ietf-yang-push |
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 |
|---|---|---|
Backup the running configuration to a file |
||
Cancel a confirmed-commit operation |
||
Cancel a notification subscription |
||
Clear the replay buffer for an event stream |
||
Terminate the current session |
||
Activate edits in <candidate> |
||
Copy an entire configuration |
||
Start receiving notifications |
||
Delete a backup configuration file |
||
Delete a configuration |
||
Delete a notification subscription by the owner session |
||
Discard edits in <candidate> |
||
Edit the target configuration |
||
Start a notification subscription |
||
Retrieve <running> or state data |
||
Retrieve all or part of a configuration |
||
Retrieve data from an NMDA datastore |
||
Retrieve N list entries at a time |
||
Retrieve YP-HA status information |
||
Retrieve the installed module-tags |
||
Retrieve session customization parameters |
||
Retrieve a YANG or YIN module definition file |
||
Retrieve the server version and build-date |
||
Retrieve the Schema Mount YANG Library information |
||
Terminate a NETCONF session |
||
Delete a notification subscription by any session |
||
Load a YANG module and its SIL code [DEPRECATED] |
||
Load a YANG module and its SIL code |
||
Load a SIL bundle (SIL code + modules |
||
Internal RPC to load <running> datastore at boot-time |
||
Lock a database |
||
Lock all configuration databases at once |
||
Modify a notification subscription |
||
No operation. [DEPRECATED] |
||
Lock part of the <running> database |
||
ietf-netconf-partial-lock |
Unlock part of the <running> database |
|
Refresh the backup-files monitoring data |
||
Internal RPC operation for configuration datastore synchronization |
||
Restart the server. [DEPRECATED] |
||
Restore the <running> database from a backup |
||
Re-synchronize a YANG Push notification subscription |
||
Set the logging verbosity level [DEPRECATED] |
||
Set the logging verbosity level |
||
Set the session customization parameters |
||
Shutdown the server [DEPRECATED] |
||
Unload a YANG module and its SIL code |
||
Unload a SIL bundle, and all its YANG modules and SIL code |
||
Unlock a database |
||
Unlock all configuration databases at once |
||
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 |
|---|---|
Specifies how access control will be enforced |
|
Allow delete-all operations on leaf-list objects |
|
Allow delete-all operations on list objects |
|
Limits sessions to specified user 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.` |
|
Specifies a YANG module to load as an annotations module |
|
Specifies the audit log of changes to the running database, after initial load is done. |
|
Specifies that no default audit log should be created when --fileloc-fhs is set to ‘true’ |
|
Append audit entries to the existing log if present; Otherwise start a new audit log. |
|
Record transactions on the candidate datastore or not |
|
Minimum debug level to generate console audit log messages |
|
Select which events are recorded in the audit log |
|
Minimum debug level to generate audit log messages |
|
Treat false when-stmts in the edit PDU as errors |
|
Maximum number of bytes o display of binary data for a YANG object |
|
Specifies a SIL bundle to load into the server at boot-time |
|
Specifies whether server will reconnect after client closes the session |
|
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. |
|
Specifies the number of retry attempts the server should attempt to the Call Home server before giving up. |
|
Specifies a NETCONF over SSH Call Home server that this server should attempt to initiate a Call Home connection at boot-time. |
|
Specifies the command used in Call Home to invoke the SSH server |
|
Specifies the filespec for the config file used in Call Home to invoke the SSH server |
|
Specifies the command used in Call Home to invoke the netconf subsystem |
|
Specifies a NETCONF over TLS Call Home server |
|
Specifies the default user name to certificate mapping (DEBUG only) |
|
Specifies a user-name to certificate mapping |
|
Specifies the directory for extra configuration parameter files |
|
Specifies the configuration file to use for parameters |
|
Convert subtree filters to XPath for internal processing |
|
Specifies that empty NP containers should be created or not |
|
Specifies that empty NP containers with read-only children should be created or not |
|
Specifies the search path for the <startup> configuration file. |
|
Specifies the amount of time to wait before retrying a DB-Config-Lock |
|
Specifies the amount of time to wait before giving up attempting to get a DB-Config-Lock |
|
Specifies the default <with-defaults> behavior |
|
Specifies that empty NP containers should be deleted or not (THIS PARAMETER IS OBSOLETE) |
|
Species a YANG module to load as a deviations module |
|
Specifies a language-specific error message |
|
Specifies the error-message language to use |
|
Specifies the maximum number of events stored in the notification replay buffer. |
|
Configure a notification event stream |
|
Configure a module to event stream mapping |
|
Force the startup and running datastores to contain the factory startup configuration |
|
Leaf list of features to disable |
|
Specifies a feature that should be enabled |
|
Specifies if a feature should be enabled or disabled by default |
|
Selects Filesystem Hierarchy Standard (FHS) directory locations |
|
Enable or disable the YP-HA feature |
|
Set the YP-HA active server to use at boot-time (for debugging only) |
|
Specify a server to be a member of the YP-HA server pool |
|
Unique string identifying the YP-HA server pool |
|
Enable edit callbacks (SIL, etc.) while in YP-HA Standby mode |
|
Set the number of seconds to wait for a <hello> PDU |
|
Get context-sensitive help with --brief or --full extension |
|
Hide the specified module from clients |
|
Include a microseconds field in the notification 'eventTime' leaf |
|
Overrides the $HOME environment variable |
|
Set the number of seconds to wait for a <rpc> PDU |
|
Enable import version best match feature |
|
Specifies the indent count to use when writing data |
|
Specifies if unverified client certificates will be accepted (DEBUG only) |
|
Run the server in YANG library mode |
|
Sets the module load path |
|
Specifies the log file to use instead of STDOUT. Refer to the Logging section for more details. |
|
Controls whether a log file will be reused or overwritten. |
|
Append stack trace information to log messages. |
|
Add additional (compiler/OS dependent) detail to stack trace information. |
|
Specify message level(s) for which stack trace information will be generated. |
|
Include stack trace information in the specified output stream(s) |
|
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). |
|
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.` |
|
Include additional information (date/time/level) with log message. |
|
Include a microseconds field in the log timestamps. |
|
Specifies verbosity level of log message output |
|
Synonym for --log-console. |
|
Specifies verbosity level of thread-specific log message output. Not active in non-threaded images. |
|
Specifies that error level log messages will be sent to STDERR. |
|
Send log message output to the syslog daemon. |
|
Specifies filter level for syslog message output. Message levels above the specified level are filtered from the syslog or vendor output stream. |
|
Directs log output to a registered, customer-written callback handler. Uses syslog if no handler is registered. |
|
Specifies how names are matched when performing UrlPath searches. |
|
Specifies the maximum number of notifications to send at once |
|
Specifies the maximum number of concurrent CLI sessions allowed |
|
Specifies the maximum number of getbulk entries to request from a GET2 callback. |
|
Specifies the maximum number of seconds a session can hold a global lock |
|
Specifies the maximum number of concurrent sessions allowed for one user |
|
Specifies the maximum number of concurrent sessions allowed |
|
Specifies tha maximum length of a quoted string to accept by the parser |
|
Specifies the maximum number of concurrent sessions allowed for all users |
|
Specifies the amount to indent in protocol messages |
|
Sets the module search path |
|
Specifies one or more YANG modules to load upon startup |
|
Specifies a module name to module-tag mapping |
|
Specifies a NETCONF capability URI to add to the server |
|
Specifies the IP address to listen for NETCONF over TLS sessions |
|
Specifies the X.509 certificate to use for NETCONF over TLS |
|
Specifies the X.509 private key to use for NETCONF over TLS |
|
Specifies the TCP port to list for NETCONF over TLS sessions |
|
Specifies the trust store file or directory for NETCONF over TLS |
|
If present, ignore the default configuration file |
|
Suppress the main log and set --log-level=none |
|
Disable internal NV-load and NV-store operations |
|
If present, the startup configuration will not be used (if present), and the factory defaults will be used instead. |
|
Disable the ypwatcher program |
|
Specifies up to 4 TCP port numbers to accept NETCONF connections from |
|
Specifies which NETCONF protocol versions to enable |
|
Specifies the maximum number of on-change push subscriptions |
|
Specifies the maximum number of periodic push subscriptions |
|
Specifies the minimum value for the 'dampening-period' parameter |
|
Specifies the minimum value for the 'period' parameter |
|
Specifies if the simulated on-change push subscriptions should be enabled |
|
Specifies the simulated on-change push subscription report type |
|
Specifies the period that will be used for simulated operational on-change push subscription |
|
Specifies whether deprecated leafs from a yumaworks-system.yang augmentation will be removed or not. |
|
Specifies a RESTCONF capability URI to add to the server |
|
Specifies the default response message encoding for RESTCONF |
|
Specifies the starting string for the server URL to use in Location header lines returned by RESTCONF. |
|
Specifies how the RESTCONF server will validate Accept and Content type headers |
|
Specifies that empty NP containers should be returned or not |
|
Controls whether "<rpc-error>" nodes will be returned in RPC output for retrieval operations |
|
Specifies how the server will return a status code upon exit |
|
Server instrumentation library (SIL) search path |
|
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) |
|
Specifies whether owner names will be saved as meta-data in the configuration data |
|
String identifying the server in the YP-HA server pool |
|
String identifying the server root when running in Multi-Instance Mode |
|
If present, will force synchronous request processing (pthread version only) |
|
Specifies that the CC callbacks should be invoked for all edit operations. (See Using Commit Completeness Callbacks) |
|
Specifies that the SIL callbacks for child nodes should be called on delete operations |
|
Specifies whether SIL callbacks are invoked for loading defaults |
|
Specifies if a missing SIL library file will be treated as an error or not. |
|
Specifies whether the SIL callbacks are invoked in reserved order for deletes or not. |
|
Force the YANG validation checks to be done before the SIL validate callbacks |
|
Specifies that the server should skip the SIL edit callbacks during the load datastore initialization phase. |
|
Specifies the global default for evaluating when-stmts on operational data nodes during retrieval operations |
|
Controls whether SIL callbacks will be done for the candidate datastore |
|
Specifies that the server should output name of the module in which the data node is defined or not. |
|
Specifies the XML or JSON file to read which contains the configuration data needed to create desired mount-points. |
|
Specifies the Schema Mount Config file encoding. Based on this encoding the server will parse the config file accordingly. |
|
Specifies the IPv4 address to listen on when the socket-type parameter is set to 'tcp'. |
|
Specifies the TCP port number to listen on when the socket-type parameter is set to 'tcp'. |
|
Specifies which type of socket the server should create for incoming <ncx-connect> protocol sessions. |
|
Specifies the startup configuration file location to override the default. Not allowed if the --no-startup parameter is present. |
|
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)` |
|
Specifies the YANG configuration to use as the factory default config |
|
Specifies if unknown nodes can be pruned at boot-time from the startup config |
|
If true then skip the root check YANG validation when loading the startup configuration at boot time. |
|
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). |
|
The number of seconds to wait for a response from a sub-system before declaring a timeout. |
|
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. |
|
Specifies the YANG module(s) the server should use for system events such as a new session, configuration change, or capability change. |
|
Specifies default sort type for system ordered lists and leaf-lists |
|
Specifies whether system ordered lists and leaf-lists should be maintained in sorted order |
|
Specifies if the <candidate> or <running> configuration should be the edit target |
|
The number of seconds to wait for the TCP connect function to finish |
|
Specifies advanced OpenSSL cipher configuration settings. |
|
Specifies whether missing CRL Distribution Point is an error |
|
Specifies how Certificate Revocation List processing is done |
|
Enable extended NETCONF over TLS logging information |
|
Allow deprecated versions of TLS to be used |
|
Specifies if leading and trailing XML whitespace should be trimmed |
|
Forces strict YANG XML ordering to be enforced |
|
Pass vendor-defined parameter string to instrumentation |
|
Prints the program version string and exits |
|
Block client sessions until <running> datastore is ready to use |
|
Treat all warnings as errors |
|
Controls how identifier lengths are checked |
|
Controls how line lengths are checked |
|
Suppresses the specified warning number |
|
Elevates the specified warning number to an error |
|
Specifies the sleep interval between ypwatcher program attempts to check availability of the server. |
|
Controls whether the server will support YANG-API/RESTCONF URL requests that contain a dash character '-' to indicate all instances of that key leaf. |
|
Enable or disable the IETF Call Home protocol |
|
Enable or disable automatic conversion to canonical data type format |
|
Enable or disable the :config-id capability URI |
|
Enable or disable the DB-Config-Lock (system-wide edit lock) |
|
Enable or disable the <error-number> leaf in <error-info> data |
|
Enable or disable the gNMI protocol |
|
Enable or disable the gRPC protocol |
|
Enable or disable allowing maintenance mode to be used |
|
Enable or disable module-tags feature |
|
Enable or disable the NETCONF over SSH protocol |
|
Enable or disable the NETCONF over TLS protocol |
|
Enable or disable NMDA support |
|
Controls whether the server will support the :notification and :interleave capabilities or not. |
|
Controls whether OpenConfig pattern syntax will be checked |
|
Enable or disable the RESTCONF protocol |
|
Enable or disable the :rollback-on-error NETCONF capability |
|
Enable or disable YANG Schema Mount support |
|
Enable or disable SNMP protocol support |
|
Enable or disable the <startup> database |
|
Enable or disable the yumaworks-support-save.yang YANG module |
|
Enable <term-msg> notification |
|
Enable or disable the :url capability |
|
Enable or disable FTP scheme in <url> parameter |
|
Enable or disable TFTP scheme in <url> parameter |
|
Enable or disable the :validate capability |
|
Enable or disable the error-severity field set to warning |
|
Enable or disable the YANG-API protocol |
|
Enable or disable the YANG/CBOR message encoding |
|
Enable or disable YANG Patch if target=running |
|
Enable or disable strict YANG 1.1 <hello> message |
|
Enable the YP-COAP protocol |
|
Enable the YP-COAP over DTLS protocol |
|
Enable or disable the YP-SHELL protocol |
|
Enable or disable the yuma-system.yang module |
|
Enable or disable the yuma-time-filter.yang module |
|
Enable or disable the yumaworks-callhome.yang module |
|
Enable or disable the yumaworks-cert-usermap.yang module |
|
Enable or disable the yumaworks-config-change.yang module |
|
Enable or disable the yumaworks-event-filter.yang module |
|
Enable or disable the yumaworks-event-stream.yang module |
|
Enable or disable the yumaworks-getbulk.yang module |
|
Enable or disable the yumaworks-ids.yang module |
|
Enable or disable the yumaworks-lock.yang module |
|
Enable or disable the yumaworks-sm-yanglib.yang module |
|
Enable or disable the yumaworks-system.yang module |
|
Enable or disable the yumaworks-templates.yang module |
|
Select the YANG/CBOR SID vs LSID Mode |
|
The starting string for the server URL to use in Location header lines returned by YANG-API. The default is 'http://localhost'. |
|
IP address to use for YP-CoaP or YP-CoAP over DTLS protocols |
|
UDP port to use for YP-CoAP over DTLS protocol |
|
UDP port to use for YP-CoAP protocol |
|
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 |
|---|---|---|
any |
Hide the specified module from client discovery. Does not affect data returned to clients. |
|
<get-support-save> gathers support information. Must build source WITH_SUPPORT_SAVE=1 |
||
<term-msg> notification used to support yp-shell terminal diagnostic messages |
||
Yuma |
||
if-modified-since filter for <get> and <get-config> |
||
Run-time configuration or NETCONF Call Home connections. |
||
Configure NETCONF over TLS 'cert-to-name' mappings |
||
Add edit data to <netconf-config-change> Event notification (Security Risk!! Review YANG module before use!!) |
||
<event-filters> container to drop specific event types |
||
<event-streams> container to configure event streams and <clear-eventlog> RPC operation |
||
<get-bulk> operation to retrieve YANG list entries |
||
Contains transport identity values to add YControl and direct sessions to ietf-netconf-monitoring.yang <session> list |
||
<get-sm-yanglib> operation to retrieve Schema Mount YANG library |
||
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. |
||
|
DB-Config-Lock Mode
The DB-Config-Lock mode allows the netconfd-pro to participate in a system-wide lock for modification of the <running> configuration datastore contents. Use of this system-wide lock require that the server is built using WITH_YCONTROL=1. The 'db_api.c' module contains APIs to allow the server and the “local” system to request and release the DB-Config-Lock.
The following CLI parameters affect DB-Config-Lock mode:
--with-db-lock=true required to use DB-Config-Lock.
--db-lock-retry-interval, --db-lock-timeout, and --subsys-timeout affect how long the server will wait for a DB-Config-Lock.
The DB-Config-Lock is described in the YANG module yumaworks-db-api.yang.
The following DB-API messages are used:
db-lock-init: Initialize the DB-Config-Lock service. The server will not allow any configuration modifications, including booting the startup configuration, until this message is properly handled by the server.
db-lock: The server sends this message to the DB-Config-Lock subsystem before the Apply/Commit/Rollback portion of an edit transaction to the <running> configuration, The validate phase callbacks are invoked without 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.
Upgrading To a New Release Train
There are some considerations needed when upgrading to a new release train. This section describes the differences between release trains and highlights any non-backward compatible changes.
From 20.10 (or earlier) to 21.10
Refer to the KnowledgeBase article
From 21.10 to 22.10
This section summarizes the new and changed features in the YumaPro SDK 22.10 release train.
YANG Module Changes in 22.10
Old ietf-inet-types.yang module removed
Version 2010-09-24 removed since it is no longer used
New YANG modules:
CLI Parameter Changes in 22.10
Added --highres-event-time
Changed eventTime timestamp to use highRes by default
Added --log-highres-datetime
high-res timestanps in 'custom' log headers
Default is false so no behavior change
Added --max-lock-hold-time
Default is 0 so no change in behavior
Added --max-user-sessions
Default is 0 so no change in behavior
Added --sil-cc-callback-all
Access new CommitCompletenes even if target=running
Default is false so no change in behavior
Added --tls-deprecated-ok
Change: TLS 1.0 now disabled by default
Must set to true to allow TLS 1.0
Added --with-error-number
Some clients do not parse the error-number correctly
Sometimes not needed
Default is to add error-number, so no behavior change
Added --tcp-connect-timeout
Changed TCP connect wait from blocking to non-blocking by default
Changed TCP timeout default from system timeout value to 10 sec by default
Added --with-yumaworks-lock
New <lock-all> and <unlock-all> operations
Default is true to add module but optional to use
New Features in 22.10
gRPC Protocol (YumaPro gRPC User Guide)
From 22.10 to 23.10
This section summarizes the new and changed features in the YumaPro SDK 23.10 release train.
Programs Removed in 23.10
The 'yangdump-sdk' program has been removed. Use the 'yangdump-pro' program instead.
YANG Module Changes in 23.10
New YANG modules:
Only enabled if --with-yang-cbor set to 'true'
The Binary Push feature is not supported for production use in this release train.
Only enabled if Schema Mount feature active
yumaworks-schema-mount-annot.yang
Only enabled if Schema Mount feature active
Only enabled if Schema Mount feature active
Only enabled if --with-yang-cbor set to 'true'
The Binary Push feature is not supported for production use in this release train.
New YANG Extensions
Add ywx:sil-xpath-function extension
Add ywx:sort-type extension
Add ywx:hidden-from-cli extension
CLI Parameter Changes in 23.10
Changed --with-yang11-hello default from false to true
This change causes YANG 1.1 module capabilities to be removed from "<hello>" and from the
/netconf-state/capabilitiescontainerMust set to 'false' to get YANG 1.0 (22.10) behavior
Set to 'true' for standards conformance and faster session startup.
Updated --audit-log-events
add bit 'rpc-error'
Default is no behavior change
Deprecate --create-empty-npcontainers
Use --return-empty-npcontainers instead.
Default is no behavior change
Add --create-empty-npcontainers-ro
Already deprecated, use --return-empty-npcontainers instead.
Default is no behavior change
-
Default is no behavior change
Add --return-empty-npcontainers
Default is no behavior change
Recommend setting to 'false'
Add --sm-config
Used by the Schema Mount feature
No default
Add sm-config-encoding
Used by the Schema Mount feature
Parameter ignored unless feature is used
-
Default is no behavior change
Used with the ywx:sort-type YANG extension
Changed --system-sorted from status deprecated to status current
Add --user-parm
No default
-
Default is enabled but no behavior change unless the --sm-config parameter is also set
Add --with-yang-cbor
Default is no behavior change
The Binary Push feature is not supported for production use in this release train.
Add --with-yumaworks-sm-yanglib
Default is enabled but no behavior change unless the --with-schema-mount and --sm-config parameters are also set
Add --yang-sid-mode
Default is no behvaior change unless --with-yang-cbor is set to 'true'.
The Binary Push feature is not supported for production use in this release train.