../_images/logo.png

YumaPro User Manual

YumaPro Introduction

YumaPro SDK is software development kit for YANG-based network management. It contains a set of programs providing a complete network management system and development environment, which implements an extensive set of features and standards

This document contains the following information:

  • YumaPro System Components

  • YumaPro Configuration

  • YumaPro XPath Reference

  • YumaPro Error Reference

YumaPro System Components

The YumaPro Tools suite provides automated support for development and usage of network management information.

All management data is defined with the YANG data modeling language.

All management operations are encoded in XML 1.0 and performed with standard NETCONF protocol operations.

../_images/main_software_components.png

The list of installed files and programs can be found in the YumaPro Installation Guide.

YANG

A YANG module define the semantics and syntax of a specific management feature. They are similar to SMIv2 (MIB) modules, but much more powerful and extensible. YANG provides the ability to define a detailed programatic interface utilizing all protocol features:

  • reusable derived data types

  • reusable groupings of objects

  • RPC operations

  • database objects

  • notifications

Network management software developers creating a new management feature start by defining the YANG module(s) for the NETCONF representation of the feature. This can include any mixture of new operations, data, and notifications. Existing YANG modules can be augmented as well.

../_images/yang_features.png

The YANG feature statement is used to define a conceptual set of optional functionality within a YANG module. Data definitions and other statements that contain the if-feature statement for the corresponding feature are part of the optional set.

Note

If an object (or ancestor) does not contain any "if-feature" statements then it is mandatory-to-implement.

If the server does not advertise a feature in its <capabilities>, then it is not supported, and all the objects that are part of the feature are not supported.

NETCONF

The mandatory components of the NETCONF protocol are defined in RFC 6241 and RFC 6242.

../_images/netconf_layers.png

The NETCONF protocol is used to provide secure access all YANG content. The server maintains a database which is accessed as if it was an XML instance document.

../_images/netconf_top_down.png

Data can be retrieved with XML (subtree) or XPath filters. Changes can be validated before being activated. Databases can be locked to prevent multiple managers from interfering with each other. Custom operations can be used to perform complex actions and perhaps return some data as well.

../_images/netconf_bottom_up.png

NETCONF can utilize several secure transport protocols. The mandatory transport (SSH2) is used by YumaPro. The OpenSSH server is used in the netconfd-pro implementation, and libssh2 library is used in the yangcli-pro implementation, to provide all SSH2 layer support.

By default, TCP port 830 (netconf-over-ssh) is used for all NETCONF communications between yangcli-pro and netconfd-pro. TCP port 22 (ssh) is also supported by default, and additional TCP ports can be configured.

NETCONF security is session-based. Privileges are granted to a session based on the username provided in the SSH connection setup.

Access control is configurable via ietf-netconf-acm.yang, based on group membership. The NACM rules permit or deny access to one or more groups, to a subset of the YANG content.

Refer to the Access Control section for more details.

YANG-based Automation

YumaPro is a 100% “native YANG” implementation. This means that YANG modules are used directly by all the tools to control all aspects of NETCONF protocol usage. There are no lossy translations, or complicated configuration steps, in order to use a YANG module. Simply load a module and start using it.

../_images/yang_source_code.png

The more machine-readable YANG clauses that are used, the more the yangcli-pro client and netconfd-pro server can automate the entire NETCONF protocol implementation.

The YANG language includes many ways to specify conditions for database validity, which traditionally are only documented in DESCRIPTION clauses:

YANG Automation Constructs

YANG Statement

Description

config

The config statement indicates if the object is writable, or read-only. The server will automatically skip config=false entries for the <get-config> operation.

default

The default statement specifies the mandatory-to-use default value, if no leaf or leaf-list is provided.

deviation

The deviation statement allows any YANG object be customized for a particular platform or implementation.

error-app-tag

The error-app-tag statement can be used within the range, length, and pattern statements. If an error occurs, the string will be used for the <error-app-tag> field in an <rpc-error> sent by the server.

error-message

The error-message statement can be used within the range, length, and pattern statements. If an error occurs, the string will be used for the <error-message> field in an <rpc-error> sent by the server.

feature

The feature statement allows a module to be conceptually partitioned into mandatory and conditional object groups. All objects with the corresponding if-feature statement will be present only if the feature is supported by the server.

import

The import statement allows definitions from other modules to be used. A specific revision date or any revision date can be used within a module.

include

The include statement allows multiple sub-modules to be combined to create one conceptual YANG module.

key

The key statement indicates a set of one or more leaf child nodes within the list entry that are used to name an instance of the list object.

length

The length statement is like the range statement, except it limits the length of string leaf and leaf-list objects.

mandatory

The mandatory statement indicates that the choice, list or leaf must be provided by the client.

max-elements

Specifies the maximum number of instances that a list or leaf-list object can have in a valid database.

min-elements

Specifies the minimum number of instances that a list or leaf-list object must have in a valid database.

must

If the object containing the must statement exists, then the XPath expression must evaluate to 'true' for the database to be valid.

pattern

The pattern statement specifies a regular expression that must evaluate to 'true' in order for the corresponding string leaf or leaf-list object to be valid.

range

The type statement can specify the range of a numeric type. Indicates the range of valid values for a numeric data type.

refine

The refine statement is defined within a uses statement, and allows the specific grouping to be customized for each individual copy of the grouping contents.

revision

The revision statement identifies the most current version of a YANG module or sub-module.

unique

The unique statement indicates an arbitrary tuple of descendant nodes within a list, which have to be unique within the list.

uses

The uses statement inserts an instance of a reusable grouping, replacing the uses node within the conceptual data tree.

when

The object containing the when statement is only allowed to exist if the XPath expression evaluates to 'true'.

YANG Language Extensions

There are several YANG extensions that are supported by YumaPro. They are all defined in the YANG file named yuma-ncx.yang. They are used to 'tag' YANG definitions for some sort of automatic processing by YumaPro programs. Extensions are position-sensitive, and if not used in the proper context, they will be ignored. A YANG extension statement must be defined (somewhere) for every extension used in a YANG file, or an error will be occur.

Most of these extensions apply to netconfd-pro server behavior, but not all of them. For example, the ncx:hidden extension will prevent yangcli-pro from displaying help for an object containing this extension. Also, yangdump-pro will skip this object in HTML output mode.

The supported YANG language extensions can be found in the Built-in YANG Language Extensions section of the YumaPro YANG Automation Guide.

YANG Compiler

The YumaPro programs all use the same centralized YANG language parser.

The complete YANG language is supported, as defined in RFC 7950. The file naming conventions defined in RFC 6020 must be used, along with all the language definition rules.

Definitions can be contained in modules and/or sub-modules.

All extension usage within YANG files is supported and saved. The application data is available to all YumaPro programs, including netconfd-pro server instrumentation.

The smidump is not part of YumaPro, but it can be utilized to convert MIB modules written in SMIv2 into YANG modules, which can then be implemented in netconfd-pro, and managed with yangcli-pro. The freely available libsmi library contains the smidump program.

YANG Module Library

Directory Layout

YumaPro can utilize several directories to store files used during operation. By default, a 'root' directory and all of its sub-directories are searched for these files. Several different roots can be searched. Generally, there is one centralized root (YUMAPRO_INSTALL) shared by all users, and one or more 'project' roots (YUMAPRO_HOME), which can be shared but may belong to a single user.

The YumaPro programs need to find and store the following types of files during operations:

  • YANG modules and submodules (*.yang):

  • XML and text data files (usually *.txt or *.xml)

  • command scripts for yangcli-pro

  • command-line-history file for yangcli-pro

The search paths used to find these files are discussed in detail in the System Configuration section.

../_images/default_directory_layout.png

Module Revisions

YANG has extensive module life cycle support. Each module or submodule has a revision date, and multiple revisions of the same module or submodule may be used at once within the same server.

YumaPro has an extensive set of mechanisms to automate the maintenance of these platform-specific 'special requirements'. A single YANG module (plus 'patches' and deviations as needed for each platform) can be published, instead of a separate version of the YANG module for each platform.

../_images/cooked_modules.png

Module Naming Conventions

YANG module names are usually lower-case. Hyphen (-), underscore (_) and period (.) characters are allowed, after the first character, which must be a letter. It is suggested that only the at sign (@) character be used as a separator between module name string components. YANG files must use the suffix '.yang'. YIN files must use the suffix 'yin'.

There are two forms of YANG file names: with and without a revision date.

module.yang

ietf-netconf-monitoring.yang

module@revision-date.yang

ietf-netconf-monitoring@2009-04-17.yang   (must be the 2009-04-17 version)

These naming conventions are important when YumaPro needs to resolve an 'import' or 'include' statement in a YANG file. Refer to the Searching for Files section for more details on YANG module search paths and the 'import-by-revision' feature of YANG.

YANG Files

YANG modules and submodules are text files encoded in UTF-8. . There is also an alternate XML encoding called YIN. Sometimes the term YANG module is used to refer to the conceptual module, whether it is encoded in YANG format or YIN format.

All YumaPro Tools programs will accept either encoding format, however line and column numbers are not correct in log messages for YIN encoded modules. Instead, each XML node is given a monotonically increasing value, and the XML document order is used instead of line numbers in error/warning messages for YIN files. The column number is always '1' for YIN files.

A module can be validated and checked for possible programming mistakes, by using the yangdump-pro program. Many 'reports' can also be generated:

The yangdump-pro program is also used to generate other files, derived from the YANG content. Refer to the Translating YANG to Other Formats section for more details.

NETCONF Managers

The NETCONF client is an application that initiates and utilizes NETCONF sessions to control and monitor a NETCONF server.

YumaPro includes the yangcli-pro application for this purpose. It can be used as a stand-alone tool with any NETCONF server.

Refer to the YumaPro yangcli-pro Manual for complete details.

NETCONF Servers

The NETCONF server is a server application that is always running on the managed device. It listens for NETCONF session requests from a NETCONF client, and allows specific users to access specific subsets of the available content (operations, database access, and notifications). It processes all incoming protocol operation requests from the client, and insulates all the instrumentation code from these protocol operations.

YumaPro includes the netconfd-pro application for this purpose. It can be run on several different platforms, or easily adapted to embedded platforms.

Refer to the YumaPro netconfd-pro Manual for complete details.

System Configuration

The YumaPro programs use YANG to define its configuration parameters. For example, the module "netconfd-pro.yang" contains the CLI and configuration file parameters for the netconfd-pro program.

YumaPro applications can accept configuration parameters from 3 sources, checked in the following order:

  1. Environment Variables

  2. Command Line Parameters

  3. Configuration File

Environment Variables

The YumaPro programs utilize system environment variables to customize and simplify configuration and operation of the programs.

These environment variables typically specify file search paths or default directory locations.

The following environment variables are used within YumaPro:

  • HOME

  • YUMAPRO_HOME

  • YUMAPRO_INSTALL

  • YUMAPRO_MODPATH

  • YUMAPRO_LOADPATH

  • YUMAPRO_DATAPATH

  • YUMAPRO_RUNPATH

$HOME

The $HOME environment variable contains the directory specification of the user's home directory, and is expected to be set by the system shell before use. The YumaPro programs expect (by default) that sub-directories and files contained in this directory will be readable and writable.

Default value: none
CLI override: --home
CLI example:
> netconfd-pro --home=/home/andy

C shell example:

setenv HOME /home/andy

Bash shell example:

export HOME=/home/andy

$YUMAPRO_HOME

The $YUMAPRO_HOME environment variable contains the directory specification of the current YumaPro project root directory. This is the path to the 'netconf' directory, within a YumaPro source tree.

Default value: none
CLI override: --yumapro-home
CLI example:
> netconfd-pro --yumapro-home=/home/andy/swdev/yumapro/trunk/netconf

C shell example:

> setenv YUMAPRO_HOME /home/andy/swdev/yumapro/trunk/netconf

Bash shell example:

> export YUMAPRO_HOME=/home/andy/swdev/yumapro/trunk/netconf

$YUMAPRO_INSTALL

The $YUMAPRO_INSTALL environment variable contains the directory specification of the YumaPro installation root directory.

Default value: /usr/share/yumapro
CLI override: none
C shell example:
> setenv YUMAPRO_INSTALL /sw/yumapro

Bash shell example:

> export YUMAPRO_INSTALL=/sw/yumapro

$YUMAPRO_MODPATH

The $YUMAPRO_MODPATH environment variable contains a list of directory specifications that should be searched (in order) to find YANG or YIN modules and submodules. It can be used to extend the search path beyond the default locations.

The syntax for this parameter is a string containing the desired directory paths, separated by colon (:) characters. If the trailing forward slash (/) character is missing, then it will be added when searching for files.

By default, each entire directory and all its sub-directory contents will be searched for the requested file. This can be overridden with the --subdirs parameter. If --subdirs=false is used, then only the specified directory will be searched instead.

Default value: none
CLI override: --modpath
CLI example:
> netconfd-pro --modpath=$HOME/modules2:/usr/local/modules”

C shell example:

> setenv YUMAPRO_MODPATH “$HOME/modules2:/usr/local/modules”

Bash shell example:

> export YUMAPRO_MODPATH=$HOME/modules2:/usr/local/modules”

$YUMAPRO_LOADPATH

The $YUMAPRO_LOADPATH environment variable contains a list of directory specifications that should be searched (in order) to load YANG or YIN modules into the server. It is supported by netconfd-pro only. It can be used to simplify loading of YANG modules.

The syntax for this parameter is a string containing the desired directory paths, separated by colon (:) characters. If the trailing forward slash (/) character is missing, then it will be added when searching for files.

By default, each entire directory and all its sub-directory contents will be searched for the requested file. This can be overridden with the --subdirs parameter. If --subdirs=false is used, then only the specified directory will be searched instead.

Default value: none
CLI override: --loadpath
CLI example:
> netconfd-pro --loadpath=$HOME/modules2”

C shell example:

> setenv YUMAPRO_LOADPATH “$HOME/modules2”

Bash shell example:

> export YUMAPRO_LOADPATH=$HOME/modules2”

$YUMAPRO_DATAPATH

The $YUMAPRO_DATAPATH environment variable contains a list of directory specifications that should be searched (in order) to find data files used by YumaPro applications. It can be used to extend the search path beyond the default locations.

Data files used by the yangcli-pro program are affected by this environment variable.

The location where the netconfd-pro program keeps the file startup-cfg.xml is also affected by this environment variable. This file contains the contents of the non-volatile <startup> database, which is loaded into the <running> database when the server boots.

The syntax for this parameter is a string containing the desired directory paths, separated by colon (:) characters. If the trailing forward slash (/) character is missing, then it will be added when searching for files.

By default, each entire directory and all its sub-directory contents will be searched for the requested file. This can be overridden with the --subdirs parameter. If --subdirs=false is used, then only the specified directory will be searched instead.

Default value: none
CLI override: --datapath
CLI example:
> netconfd-pro --datapath=$HOME/mydata:$HOME/project1/data”

C shell example:

> setenv YUMAPRO_DATAPATH “$HOME/mydata:$HOME/project1/data”

Bash shell example:

> export YUMAPRO_DATAPATH=$HOME/mydata:$HOME/project1/data”

$YUMAPRO_RUNPATH

The $YUMAPRO_RUNPATH environment variable contains a list of directory specifications that should be searched (in order) to find script files used by YumaPro applications. It can be used to extend the search path beyond the default locations.

Script files used by the yangcli-pro program are affected by this environment variable.

The syntax for this parameter is a string containing the desired directory paths, separated by colon (:) characters. If the trailing forward slash (/) character is missing, then it will be added when searching for files.

By default, each entire directory and all its sub-directory contents will be searched for the requested file. This can be overridden with the --subdirs parameter. If --subdirs=false is used, then only the specified directory will be searched instead.

Default value: none
CLI override: --runpath
CLI example:
> netconfd-pro --runpath=$HOME/scripts:/usr/local/scripts”

C shell example:

> setenv YUMAPRO_RUNPATH “$HOME/scripts:/usr/local/scripts”

Bash shell example:

> export YUMAPRO_RUNPATH=$HOME/scripts:/usr/local/scripts”

Searching for Files

All YumaPro programs search for YANG and other files in the same manner, using the same configuration parameters. The current working directory is included in this search path, so it is important to consider the directory in which a YumaPro program is invoked. The search ends as soon as a suitable matching file is found.

There are two types of module searches:

  1. searches on behalf of configuration parameters

  2. searches on behalf of YANG import or include statements

The first term in a path specification may contain special character sequences:

  • If the first character is the forward slash ('/'), then the entire path specification is used as an absolute path specification.

    /usr/share/yang/modules
    
  • If the module suffix (e.g., .yang) is present, and the first character is not the forward slash ('/'), and no special characters are found instead, then the entire path specification is used as an relative path specification, starting from the current working directory.

    ../more-modules/test7.yang
    ./this-dir/my-module.yang
    testmodule.yang
    old-modules/version7/device-types.yang
    
  • If the first character is the tilde ('~') character, followed by the forward slash ('/') character, then the file search will start in the current user's $HOME directory .

    ~/modules/test/test.yang
    
  • If the first character is the tilde ('~') character, followed by a user name, and then the forward slash ('/') character, then the file search will start in the specified user's $HOME directory . If the user is unknown, then the path specification is invalid.

    ~andy/modules/test/test.yang
    
    ~fred/scripts
    
  • If the first character is the dollar sign ('$') character, followed by an environment variable name, and then the forward slash ('/') character, then the file search will start in the directory indicated by the contents of the environment variable. If the variable is unknown, or its contents do not represent a valid directory location, then the path specification is invalid.

    $WORKDIR/tests/test-all-interfaces
    
    $YUMAPRO_HOME/data/startup-cfg.xml
    

Whenever YumaPro searches a directory, it checks for the expected file type, but ignores the following:

  • all files and sub-directories that begin with the period (.) character

  • any directory named 'CVS'

The following environment variables affect file searches:

The following configuration parameters affect file searches:

YumaPro Search Root?

../_images/yumapro_root.png

The YumaPro Tools programs will search for some types of files in default locations

  • YANG Modules: The 'modules' sub-directory is used as the root of the YANG module library.

  • Client Scripts: The yangcli-pro program looks in the 'scripts' sub-directory for user scripts.

  • Program Data: The yangcli-pro and netconfd-pro programs look for saved data structures in the 'data' sub-directory.

Searching YumaPro Roots

Proper management of YANG files and other data files is important. Make sure the correct modules and revisions of those modules will be found by being aware of the search paths used by the YumaPro tools.

../_images/search_yumapro_root.png
  1. $HOME Directory

The first YumaPro root checked when searching for files is the directory identified by the $HOME environment variable. If a $HOME/modules, $HOME/data. and/or $HOME/scripts directory exists, then it will be checked for the specified file(s).

  1. The $YUMAPRO_HOME Directory

The second YumaPro root checked when searching for files is the directory identified by the $YUMAPRO_HOME environment variable. This is usually set to private work directory, but a shared directory could be used as well. If a $YUMAPRO_HOME/modules, $YUMAPRO_HOME/data. and/or $YUMAPRO_HOME/scripts directory exists, then it will be checked for the specified file(s).

  1. The $YUMAPRO_INSTALL Directory

The last YumaPro root checked when searching for files is the directory identified by the $YUMAPRO_INSTALL environment variable. If it is not set, then the default value of /usr/share/yumapro is used instead.

This is usually set to the public directory where all users should find the default modules. If a $YUMAPRO_INSTALL/modules, $YUMAPRO_INSTALL/data. and/or $YUMAPRO_INSTALL/scripts directory exists, then it will be checked for the specified file(s).

YumaPro Work Directory

There is a directory named $HOME/.yumapro created by yangcli-pro or netconfd-pro for data files and temporary files. It is created in the users home directory, if the $HOME environment variable or --home parameter is defined.

Unless the --fileloc-fhs=true setting is used, this directory will be used as the default location to save the startup-cfg.xml file by netconfd-pro, if no startup file is specified in the CLI parameters, and no existing startup file is found in the data file search path.

This directory is also used as the default location to store the .yangcli-pro_history file for yangcli-pro command line history recall.

The $HOME/.yumapro/tmp directory is used by yangcli-pro to create session-specific sub-directories where all the YANG modules from the server for the current session are stored. If the --autoload=false parameter is used, then these temporary directories will not be created by yangcli-pro.

Parameter Searches

A parameter search is started on behalf of a CLI parameter, such as the --module parameter, used by the yangdump-pro program. A search of this type can include directory path and file extension in the search parameter. If a filename with a file extension (must be '.yang') is given, then only that exact file will be checked. The current working directory will be used in this case, if no directory path (or a relative directory path) is provided.

If the exact filename is not found, then the search failed.

If a parameter based search does not have any directory path or file extension fields present, then a parameter search is the same as an import/include search.

Import/Include Searches

An import or include search is started on behalf of a YANG 'import' or 'include' statement. A search of this type includes only the module or submodule name, with no directory or file extension present. An optional 'revision-date' statement can be used in YANG, which means only a version of the YANG file with that exact current revision date will be used.

There are separate search algorithms, depending on whether the revision-date is used in the YANG import or include statement, and whether the imported or included module has a current revision statement.

Mode 1: import-by-revision

In this example, an import statement is causing a search for a module named 'foo' with a revision date of '2009-01-15'.

If a revision-date is used in the import or include statement, then the module search path will be checked as follows:

First, find a file with the same revision-date in the file name:

import foo {
  revision-date “2009-01-15”;
  prefix foo;
}

If the file 'foo.2009-01-15.yang' is found, and the current revision statement in the module is equal to '2009-01-15', then the search is successfully terminated.

If the file is not found, or the most current revision date is not correct, then the module search is repeated for 'foo.yang' (no revision date). If the file 'foo.yang' is found, and the current revision statement in the module is equal to '2009-01-15', then the search is successfully terminated.

If the file is not found, or the most current revision date is not correct, then the module search failed.

Mode 2: import any revision

If no file name with the specified revision-date value is found, then the module search path is checked for a file with no revision-date in the file name:

import foo {
  prefix foo;
}

If the file 'foo.yang' is found, then it is used, regardless of the most current revision date (if any) found in the module. If it is not found then the module search failed.

The first instance of 'foo.yang' in the module search path will be used, even if a more current version is available, later in the search path.

This behavior can be overriden in the server using the "bestmatch" feature. If the --import-version-bestmatch CLI parameter is set to true, then the module path will be scanned before the server starts. The most recent revision date will be found for each module. When import-without-revision is used, then this "bestmatch" revision will be used. The default on the server is false.

File Search Paths

YumaPro uses configurable search paths to find the various files that are needed during operation.

Module Search Path

  • If the module parameter is specified with a path or file suffix, the that filespec is tried, relative to the current working directory. If it is not found, or not the correct revision date, then the search terminates in failure.

    --module=../test.yang
    
  • If the module is specified without any path or file extension fields, then the module search path is checked, in order. The first step which produces a match terminates the search successfully. If all steps are exhausted and no match is found then the search terminates in failure.

    --module=foo
    
    1. The current working directory is checked. No sub-directories are checked, if any are present.

    2. Each directory specified in the $YUMAPRO_LOADPATH environment variable, or set with the --loadpath configuration parameter, is checked.

      1. If the --subdirs=false parameter is set, then only each top-level directory will be checked. If it is not set, then sub-directories will be searched.

    3. Each directory specified in the $YUMAPRO_MODPATH environment variable, or set with the --modpath configuration parameter, is checked.

      • If the --subdirs=false parameter is set, then only each top-level directory will be checked. If it is not set, then sub-directories will be searched.

    4. The $HOME/modules directory is checked.

      • If the --subdirs=false parameter is set, then only each top-level directory will be checked. If it is not set, then sub-directories will be searched.

    5. The $YUMAPRO_HOME/modules directory is checked.

      • If the --subdirs=false parameter is set, then only each top-level directory will be checked. If it is not set, then sub-directories will be searched.

    6. The $YUMAPRO_INSTALL/modules directory is checked.

      • If the --subdirs=false parameter is set, then only each top-level directory will be checked. If it is not set, then sub-directories will be searched.

Data Search Path

YumaPro programs can store data used during operation.

An example of a data file is the startup configuration file used by netconfd-pro, usually called startup-cfg.xml.

  1. If the file name has an absolute path specification, then that exact file location is tried. If no match is found, then the search will terminate in failure.

  2. Each directory specified in the $YUMAPRO_DATAPATH environment variable, or set with the --datapath configuration parameter, is checked.

    • If the --subdirs=false parameter is set, then only each top-level directory will be checked. If it is not set, then sub-directories will be searched.

  3. The current working directory is checked. No sub-directories are checked, if any are present

  4. The $HOME/data directory is checked.

    • If the --subdirs=false parameter is set, then only each top-level directory will be checked. If it is not set, then sub-directories will be searched.

  5. The $YUMAPRO_HOME/data directory is checked.

    • If the --subdirs=false parameter is set, then only each top-level directory will be checked. If it is not set, then sub-directories will be searched.

  6. The $HOME/.yumapro directory is checked.

  7. The $YUMAPRO_INSTALL/data directory is checked.

    • If the --subdirs=false parameter is set, then only each top-level directory will be checked. If it is not set, then sub-directories will be searched.

  8. The /usr/share/yumapro/data directory is checked.

    • If the --subdirs=false parameter is set, then only each top-level directory will be checked. If it is not set, then sub-directories will be searched.

  9. The /etc/yumapro directory is checked.

Script Search Path

The yangcli-pro program can store script files used during operation.

  1. If the file name has an absolute path specification, then that exact file location is tried. If no match is found, then the search will terminate in failure.

  2. The current working directory is checked. No sub-directories are checked, if any are present.

  3. Each directory specified in the $YUMAPRO_RUNPATH environment variable, or set with the --runpath configuration parameter, is checked.

    • If the --subdirs=false parameter is set, then only each top-level directory will be checked. If it is not set, then sub-directories will be searched.

  4. The $HOME/scripts directory is checked.

    • If the --subdirs=false parameter is set, then only each top-level directory will be checked. If it is not set, then sub-directories will be searched.

  5. The $YUMAPRO_HOME/scripts directory is checked.

    • If the --subdirs=false parameter is set, then only each top-level directory will be checked. If it is not set, then sub-directories will be searched.

  6. The $YUMAPRO_INSTALL/scripts directory is checked.

    • If the --subdirs=false parameter is set, then only each top-level directory will be checked. If it is not set, then sub-directories will be searched.

Configuration Files

The YumaPro program configuration parameters can be stored in text or XML files.

../_images/default_linux_dirs.png

The --config parameter is used to specify that configuration parameters should be retrieved from a file instead of the command line.

Any other configuration parameter (except --config) can be stored in a configuration file used for program input.

XML Configuration Files

The XML format for these files follows the structure of the NETCONF <config> element. Each parameter is stored within a container identifying the application which it is being configured. The netconfd-pro stores its non-volatile <startup> database in this format. XML configuration file contents can appear in any order.

The following configuration parameters affect the generation and display of XML configuration files by netconfd-pro:

The following configuration parameter affects the location of XML configuration files by netconfd-pro:

  • --datapath

  • $YUMAPRO_DATAPATH environment variable

Note : The IETF may standardize this container format soon. Do not rely on the top-level namespace URI. Any top-level element name <config>, in any namespace (even none), should be expected to contain a complete NETCONF database, or a subset of a NETCONF database.

The following example show some database objects from the NETCONF Access Control Model (yuma-nacm.yang), in XML configuration file format.

<?xml version="1.0" encoding="UTF-8"?>
<nd:config xmlns:nd="http://netconfcentral.org/ns/netconfd-pro">
   <nacm:nacm xmlns:nacm="http://netconfcentral.org/ns/yuma-nacm">
      <nacm:groups>
         <nacm:group>
            <nacm:groupIdentity>nacm:admin</nacm:groupIdentity>
            <nacm:userName>andy</nacm:userName>
            <nacm:userName>fred</nacm:userName>
            <nacm:userName>barney</nacm:userName>
         </nacm:group>
      </nacm:groups>
      <nacm:rules>
         <nacm:moduleRule>
            <nacm:moduleName>netconf</nacm:moduleName>
            <nacm:allowed-rights>read write exec</nacm:allowed-rights>
            <nacm:allowed-group>nacm:admin</nacm:allowed-group>
         </nacm:moduleRule>
      </nacm:rules>
   </nacm:nacm>
</nd:config>

Text Configuration Files

The YumaPro text configuration file format is based on some common Unix .conf file formats:

  • A hash mark until EOLN is treated as a comment

    # this is a comment
    
    log-level info # this is also a comment
    
  • All text is case-sensitive

  • Whitespace before or within a line is not significant

  • The 'end a line' (EOLN) character ('n') is used to end a command, so whitespace at the end of a line is significant.

  • To enter a command on multiple lines, use an escaped EOLN (backslash-EOLN) for all but the last line

    this is a command line
    
    this is the start \
    of a long \
    three line command
    
    this is a new command
    
  • A YANG container parameter is represented by the container name, followed by a left curly brace ('{'), zero or more child nodes, and then a right curly brace ('}').

    yangdump-pro {
        # set some display control parameters
        log-level debug2
        warn-linelen 72
        indent 4
    }
    
  • A YANG list parameter is represented by the list name, followed by a whitespace separated sequence of key leaf values, followed by a left curly brace ('{'), zero or more child nodes, and then a right curly brace ('}').

ifStackEntry  11 42 {
        # the key leafs will also printed here
        ifStackHigherLayer 11
        ifStackLowerLayer 42
        ifStackStatus active
}
  • Configuration files which are used with command line parameters may include program parameters for multiple applications.

    • Only the top-level container that matches the name of the program will be used.

    • Any other top-level containers will be ignored

    • Only the first instance of the desired program container will be used. Any additional containers will be ignored.

      // test.conf
      yangdump-pro {
          # common yangdump-pro parameters here
      }
      
      yangdiff-pro {
          # common yangdiff-pro parameters here
      }
      
  • Configuration file parameters can appear in any order. Only list index strings need to appear in their defined order.

  • The following configuration parameters affect generation and display of text configuration files

Configuration File Environment Variables

Text configuration files can use environment variable expressions within the value string.

Starting in 20.10-9 environment variable syntax is supported.

Example: variable named MYHOME could be used in the expression “$(MYHOME)”

netconfd-pro {
    home $(MYHOME)
    module test
    no-watcher
}
  • Variable syntax is standard '$' + '(' + <NcxName> + ')'

  • Variable name must be valid NcxName syntax (1 - 64 chars)

  • Unquoted and Double quoted strings will be checked for variable replacement.

  • Single quoted strings will not be checked, and treated as verbatim strings (consistent with YANG syntax rules)

  • Multiple variable expressions can be used in the same expression

  • Unknown or invalid variable names in a variable expression will cause that expression to be replaced by an empty string.

  • Only conf file simple variables (leaf or leaf-list) can use an environment variable expression

Example invocation of netconfd-pro using environment variables set on the command line:

> MYHOME=/tmp/lab1 netconfd-pro config=test1.conf

Example config file using some valid variable expressions:

netconfd-pro {
    module $(MOD1)
    module "$(MOD2)"
    log-level debug$(LEVEL_NUM)
    event-stream "stream-$(STREAM_PART1)-$(STREAM_PART2)"
}

Logging

All YumaPro programs are capable of generating informational messages of various kinds. By default, these will be directed to STDOUT. With the addition of specific startup parameters, the output may instead be directed to either a file, or to a “syslog” or vendor-specific daemon (if configured on the local system). Depending on the exact set of parameters specified, varying output may be directed to a combination of these “streams”.

Message types include error, warning, general information, and debugging related detail.

The following “levels” are defined (in order from “lowest” to “highest”):

  • error

  • warn

  • info

  • debug

  • debug2 (more detailed)

  • debug3 (even more detailed)

  • debug4 (most detailed)

These keywords may be specified to the log-levelcommand, either via the command line (see bootstrap CLI below) or the config file:

  • --log-level=debug (command line)

  • log-level debug (config file)

By default, without any explicit configuration, all programs use “info” as the log level. The log level values are “ordered” and “cumulative”, meaning that log messages will be generated at all levels up to and including the specified level. For example, if --log-level=debug is specified on the command line, error, warning, info and debug level messages will be output. Debug2, debug3, and debug4 level messages will be suppressed.

Note that netconfd-pro supports all log commands described below. Yangcli-pro support is similar with the exception of thread-specific commands. Yangdiff-pro and Yangdump-pro support only the log, log-append, and log-level commands.

Logging related commands may be grouped roughly into 3 categories:

  • Output Stream – where to direct log message output.

  • Detail – what supporting information to include.

  • Debugging and Development – information useful to developer debugging and bug reporting.

Logging Output Stream Commands

In the examples below, command line CLI syntax will be used. Equivalent functionality can be achieved through using a config file instead.

By default, log message output is directed to STDOUT. If the --log command is used to specify a valid filename, messages are sent to a file instead. If --log-syslog is specified, messages are sent to the local syslog daemon. If --log and --log-syslog are both specified, both streams receive log message output. To display the output again via STDOUT, add the --log-console command.

There is an additional customer-specific logging capability analogous to --log-syslog. Syslog output may be directed to a customer-written and registered callback function by using the --log-vendor capability.

  • --log=<filename>:** Send log message output to <filename> instead of STDOUT.

  • --log-append: Append to existing log file without first truncating it.

  • --log-syslog: Direct all logger output to the syslog daemon.

  • --log-console: If --log and/or --log-syslog are present, duplicate logger output via STDOUT.

  • --log-mirroring: Synonym for --log-console.

  • --log-stderr: If STDOUT is in use, direct “error” level log messages to STDERR instead.

  • --log-vendor: If present, log messages will be directed to a customer-written and registered callback function. (In the absence of a registered callback, this parameter will direct logging messages to syslog. This facilitates stand-alone testing.) Relative to the different output streams, this parameter behaves like --log-syslog as described above. Note that --log-syslog and --log-vendor are mutually exclusive. Enabling this functionality is explained in more detail by an API specified in the YumaPro yp-system API Guide.

Logging Detail Commands

  • --log-level=<level>: Output standard log messages up to and including the specified level. Valid level keywords are those listed above in Section 4.4. By default, the infolevel is used.

  • --log-pthread-level=<level>: Output thread-specific log messages up to and including the specified level. (Note that these messages are generated in images with pthreads support only). Valid level keywords are those listed above in Section 4.4. By default, the info level is used. This output will appear in the syslog output stream only if allowed by the applicable stream filter (i.e., --log-syslog-level).

  • --log-syslog-level=<level>: Output syslog-directed messages up to and including the specified level. Valid level keywords are those listed above in Section 4.4. By default, the info level is used.

    Syslog stream output is now filtered via this directive. This means, for example, that syslog output could be limited to standard operational “info” level messages while a log file was used to capture “debug” level output.

  • --log-header=”<keyword-list>”: Prepend log-level and date/time information to each log message. Valid keywords include:

    • custom – Date/time information is in YANG canonical format.

    • localtime – Date/time information is in local time.

  • Multiple keywords may be specified. Keyword(s) should always be enclosed by double quotes and separated by spaces.

  • Note that syslog output does not receive this treatment since syslog adds its own header information, based on how it is configured.

Logging Debug and Development Commands

Generally these commands are used internally, as well as by developers with a source code license. In addition using one or more of the commands in this group may be requested by customer support in order to help with debugging issues in the field.

  • --log-backtrace=<max-frames>: Append stack trace information to each log message. Display a maximum of <max-frames> call frames. Use the value 0 to specify the internal default (20).

  • --log-backtrace-level=”<keyword-list>”: If --log-backtrace is present, generate stack trace detail for the specified log level(s) only. Valid keywords include those listed above for --log-level. Multiple level keywords may be specified. Keyword(s) should be enclosed by double quotes and separated by spaces.

  • --log-backtrace-detail: Generate additional, more detailed stack trace information (specifics depend upon compiler and host operating system).

  • --log-backtrace-stream=”<keyword-list>”: If --log-backtrace is present, limit stack trace detail for the specified log message streams only. Valid keywords include:

    • logfile

    • stdout

    • stderr

    • syslog

    • vendor

    • Multiple keywords may be specified. Keyword(s) should always be enclosed by double quotes and separated by spaces.

Note that in order to provide stack trace information to the GNU GDB debugger, a special image build may be required (with debug symbols and statically linked libraries).

Logging Examples

The following examples use the command line version of the syntax (see the Bootstrap CLI section below for more information).

By default, logging output goes to STDOUT:

mydir> netconfd-pro --superuser=marco --log-level=debug

Running netconfd-pro server (5.0.aa088bf)

New session 1 created OK

Session 1 for marco@127.0.0.1 now active (base:1.1)

Log output may be redirected to a file instead of STDOUT:

mydir> netconfd-pro --superuser=marco --log-level=debug > output.log

Error level log output may be directed to STDERR even while other log output is redirected to a file:

mydir> netconfd-pro --superuser=marco --log-level=info --log-stderr --logX >> output.log

Error: Unknown parameter (logX)

Logging output may also be directed to a file using the --log=<filename> CLI command. In this case, all output is sent to the log file (including error level messages). No output will appear on STDOUT beyond the location and name of the newly opened log file. The --log-stderr directive, if specified, is a NOP:

mydir> netconfd-pro --superuser=marco --log-level=info --log=logfile

Logging output may be directed instead to SYSLOG. In this case, netconfd-pro messages are designated as "daemon" level, while yangcli-pro messages are designated as "user" level output. The YumaPro debug level of each message is translated into an appropriate SYSLOG priority level:

mydir> netconfd-pro --superuser=marco --log-level=info --log-syslog

No output will be directed to STDOUT, STDERR, or a log file.

The presence of --log and --log-syslog commands together will cause log output to be sent to the specified log file after the message is sent for SYSLOG processing.

mydir> netconfd-pro --superuser=marco --log-level=debug --log-syslog --log=logfile

No output will be directed to STDOUT or STDERR

The addition of the --log-console directive will cause log output to be displayed via STDOUT, after the message is sent for SYSLOG and/or log file processing:

mydir> netconfd-pro --superuser=marco --log-level=debug --log-syslog --log=logfile --log-console

The presence of --log and --log-syslog commands together will cause log output to be sent to the specified log file after the message is sent for SYSLOG processing. It is possible to include different debug levels in the two different output streams by using the --log-syslog-level filter. The following will send debug level messages to the log file, but restrict syslog content to info level message output:

mydir> netconfd-pro --superuser=marco --log=logfile --log-level=debug --log-syslog --log-syslog-level=info

No output will be directed to STDOUT or STDERR

Logging output to STDOUT, STDERR, or a log file, whether direct or "mirrored" may be "customized" with date, time, and debug level information. This is the purpose of the --log-header=”custom” directive. The date/time string may be changed from the YANG default "Zulu" (UCT) format to use local time by including the localtime keyword.

mydir> netconfd-pro --superuser=marco --log-level=debug --log-header=”custom”

or

mydir> netconfd-pro --superuser=marco --log-level=debug --log-header=”custom localtime”

It is also possible to include call stack trace information (“backtrace”) within the logging message stream (including SYSLOG). For example:

mydir> netconfd-pro --superuser=marco --log-level=debug --log-syslog --log=file.log --log-backtrace=0

Will display as many as 20 stack frames of backtrace information (default). Examples of output generated by the command above follow:

Log file:

agt_ses msg ready for session 1

--Backtrace:
[0x809ee3b][0x80760d1][0x806adbc][0x805d0a4][0x805d26d][0xb74af113][0x805cbf1]

SYSLOG:

[debug] [daemon] [Jul 5 19:03:37] netconfd-pro[7576]:### agt_ses msg ready for session 1 ###

[info] [daemon] [Jul 5 19:03:37] netconfd-pro[7576]:### --Backtrace:
[0x80760d1][0x806adbc][0x805d0a4][0x805d26d][0xb74af113][0x805cbf1] ###

Given the above example, with logging info being directed via multiple streams, it is possible to restrict backtrace output to say, just the SYSLOG file, or just the console or log file:

mydir> netconfd-pro --superuser=marco --log-level=debug --log-syslog --log-console \
   --log-backtrace=33 --log-backtrace-stream=”stdout”

In the above example, backtrace info appears only on the console stream. By contrast, backtrace info will only be included in the SYSLOG file in the next example:

mydir> netconfd-pro --superuser=marco --log-level=debug --log-syslog \
   --log-console --log-backtrace=33 --log-backtrace-stream=”syslog”

Production of backtrace info can be restricted to one or more debugging levels with the addition of the --log-backtrace-level directive:

mydir> netconfd-pro --superuser=marco --log-level=debug2 --log-syslog \
   --log-console --log-backtrace=33 --log-backtrace-level=”error warn debug2”

Any of error, warning, or debug2 level log entries displayed on either the console or via syslog will include backtrace detail. Info and other debug level messages would NOT include backtrace detail.

Logging in PTHREADS Images

A NETCONFD-PRO image that uses POSIX threads to improve performance on multi-core systems may be built by including PTHREADS=1 on the make command line. (See the Developers Manual for more information on this option.)

In order to identify individual threads in log output, a thread/session identifier is added to the pre-pended header information, when --log-header=”custom”** is used as a CLI or config parameter when the server is run.

This thread/session id has the form:

[tid.sid] where tid is a thread id, and sid is a session id.

Note that thread ids begin with 1 and increment forever, as new threads are created. On the other hand, session ids are limited, occurring within a range of {1 .. max}, where “max” is the maximum number of sessions allowed on the server. A session id of “0” indicates “no session” is associated with the thread in question.

Session ids may be reused as sessions come and go on the server. Note that there is a one-to-one correspondence between threads and sessions, so if the maximum number of sessions is limited, so is the maximum number of threads present on a server at any given time.

Following successful initialization, 4 threads are present on the server. (Note: this may vary between different releases of the server.)

  • [...]: Main thread

  • [1.0]: Background thread (Bkgd Thread)

  • [2.0]: Connect thread (CX Thread)

  • [3.0]: Timer thread (Tmr Thread)

The “Main” thread represents the initial stream of execution and performs initialization in a way that is essentially identical to that of a non-threaded image.

The background thread has specialized duties that will be described elsewhere in this manual set.

The timer thread is responsible for periodically servicing a timer event queue.

The connect thread listens to a well known socket for new connection requests from clients. It is responsible for creating new sessions. When this happens, a “Receive Thread” (RX Thread) is also created and associated with each new session.

Assume for example that two new client sessions are established soon after the server initializes. Log output headers for these sessions will include one of the following thread/session ids:

  • [4.1] = Thread 4, session 1

  • [5.2] = Thread 5, session 2

Note that one should never see the same session id with two different thread ids, unless the old session was closed or killed and a new session created that reused the old session id.

Bootstrap CLI

Since YumaPro programs use YANG to define CLI parameters, there needs to be an initial bootstrap CLI phase, in order to process parameters which affect the way YANG files are processed.

The bootstrap CLI is not as flexible as the main CLI processor, and the syntax is more strict. Parameters must be entered in either of the following forms:

  • --name

  • --name=value

If parameters are not entered in this format, then they will be skipped until the main CLI parameter processing is done. This may cause undesirable changes in key parameters, such as the module search path.

The following configuration parameters are also bootstrap parameters, and will take affect immediately, if entered from the command line:

  • --log-xxx: All the logging parameters described in the previous section.

  • --home: use the specified home directory. This will override the $HOME environment variable, if it is set

  • --modpath: use the specified module search path. This will override the $YUMAPRO_MODPATH environment variable, if it is set

  • --yumapro-home: use the specified project root. This will override the $YUMAPRO_HOME environment variable, if it is set

Configuration Parameters

Command line parameters are used to provide input to YumaPro programs when they are invoked. They are also used extensively by the yangcli-pro program, to represent RPC method input parameters and database nodes which are part of NETCONF operation content, such as the <config> parameter within the <edit-config> operation.

Parameter Syntax

A CLI parameter has 2 forms:

  • Parameter contains a YANG type of 'empty' or a zero-length 'string':

<prefix><parameter-name>
  • Everything else:

<prefix><parameter-name><separator><value>

There are up to 4 components in a CLI parameter:

  1. prefix: consists of 0, 1, or 2 consecutive dash characters.

  2. parameter name: name of the parameter. A partial name may be used if it is unique.

  3. separator: either consists of the 'equals sign' character ('='), which may be preceded or followed by whitespace, or just whitespace with no equals sign character.

  4. value: a quoted or unquoted string, an empty string is only allowed if quotes are entered.

The following example shows some ways the leaf 'foo' could be entered as a CLI parameter:

leaf foo {
  type uint32;
}
  foo=7
 -foo=7
--foo=7
--foo =7
  foo 7
 -foo 7
 -foo = 7
--foo 7
--foo "7"
  foo 7

ncx:cli Extension

The ncx:cli extension is used in in YANG container definitions, which represent the program CLI parameters, not NETCONF database parameters. It does not take any parameters, and is defined in yuma-ncx.yang.

container yangcli-pro {
    ncx:cli;

    // all the yangcli-pro CLI parameters

}

If this extension is present, then netconfd-pro will ignore the container when loading the database object definitions. Only the program with the same name as the container will use the CLI parameter definition.

Default Parameter Extension

The ncx:default-parm extension is used within a container with an ncx:cli extension, or within an 'input' section of an RPC operation definition. It is defined in yuma-ncx.yang.

container yangdump-pro {
    ncx:cli;
    ncx:default-parm module;

    // all the yangdump-pro CLI parameters
 }

When invoking the yangdump-pro program, the default CLI parameter is --module. These two command lines are equivalent:

mydir> yangdump-pro --module=test1 --module=test2

mydir> yangdump-pro test1 test2

A string that does not start with any dashes will still be tried as a parameter name, before trying the default parameter. If the value used for a default parameter conflicts with another parameter name, then the normal form must be used, instead of this form.

mydir> yangdump-pro log-app test1

Even if there was a module named 'log-app', it would not be tried as a --module parameter, since it also matches the --log-append parameter.

The default parameter form is can be used in conjunction with shell wildcard characters, depending on the shell.

mydir> yangdump-pro *.yang

mydir> yangdump-pro --subtree=.

XPath Reference

The XPath 1.0 path specification language is supported in all YumaPro Tools programs, as specified in the YANG language specification. There are also some additional variables and XPath functions, available in all XPath expressions.

A custom XPath implementation is used, which is based on the internal data structures maintained within the program (i.e., object tree or data tree). No CPU or memory is wasted converting these data structures to actual XML documents for XPath processing.

XPath 1.0

All functionality defined in the XPath 1.0 specification is supported.

There are some restrictions, which are specific to the YANG standard:

  • The 'attribute' and 'processing-instruction' axes are always empty.

  • YANG identityref leaf values need to be entered within quotes or they will be interpreted as XML qualified node names.

  • The server may not maintain consistent XML document order for system-ordered data. This affects expressions which rely on XML document order to be precise and completely static. A NETCONF server is only required to maintain XML document order for user-ordered lists and leaf-lists, and only relative to a particular object, not the entire document.

XML Namespaces

The XPath implementation allows a more liberal syntax than the XPath 1.0 specification allows. Refer to section 4.6 of RFC 8407 for XPath usage guidelines.

Note

If XML namespaces are used, they must be used correctly.

Example request using XML namespaces in an XPath expression:

 <?xml version="1.0" encoding="UTF-8"?>
 <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
    message-id="2"
    xmlns:sys="http://netconfcentral.org/ns/yuma-system">
    <nc:get>
       <nc:filter type="xpath" select="/sys:system"/>
    </nc:get>
 </nc:rpc>

Note the text with the "sys" prefix which is defined by the "xmlns:sys" attribute. This 'xmlns' attribute does not have to appear exactly as specified, or within the <rpc> element. It can appear in any legal manner. Refer to the XML Namespaces 1.0 specification for more details.

Example request not using XML namespaces in an XPath expression:

 <?xml version="1.0" encoding="UTF-8"?>
 <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
    message-id="3">
    <nc:get>
       <nc:filter type="xpath" select="/system"/>
    </nc:get>
 </nc:rpc>

YANG Specific XPath Behavior

The YANG language requires some minor changes and additions to the XPath 1.0 specification:

  • The 'current' function from XPath 2.0 is supported.

  • The NULL XML namespace is mapped to the current YANG module XML namespace, when processing an XPath expression within a YANG module (e.g., must statement).

  • A NETCONF database is treated as a conceptual XML instance document with zero or more top-level elements. This is consistent with XSLT behavior. XML 1.0 requires a single top-level element,so external XML documents representing a NETCONF database always start with the <nc:config> element (config element in the NETCONF XML namespace).

Custom XPath Variables

The XPath specification supports system variables to be accessed within XPath expressions.

Within the yangcli-pro program, all user and system variables available to a script are also available as XPath variables within XPath expression evaluation (e.g., if, eval, and while commands).

For example, a variable named 'myvar' would be accessed within an XPath expression as '$myvar'.

user

An XPath variable called 'user' is supported in the yangcli-pro and netconfd-pro programs. It is equal to the NETCONF user name associated with the session evaluating the XPath expression. It is provided to be used in data rules within the NETCONF Access Control Model (NACM).

Custom XPath Functions

The following XPath functions are added to the XPath 1.0 Function Library, in addition to the 'current' function from XPath 2.0.

module-loaded

The module-loaded function tests whether the specified module is loaded within the program.

boolean module-loaded (module-name [, revision-date])

Parameters:

  • Parameter 1:

    • Type: String

    • Usage: Mandatory

    • Purpose: Specifies the module name to check.

  • Parameter 2:

    • Type: String

    • Usage: Optional

    • Purpose: Specifies the YANG revision date string for module indicated by parameter 1.

Returns: Boolean

  • true: the specified module is loaded

  • false: the specified module is not loaded, possibly not known

Errors:

  • Missing parameter error if no parameters provided.

  • Extra parameters error if more than 2 parameters provided.

  • All unknown parameter values cause a 'false' result.

Example:

yangcli-pro> if "module-loaded('yuma-system', '2009-12-27')"
yangcli-pro> log-info 'correct yuma-system module loaded'
yangcli-pro> else
yangcli-pro> log-error 'Wrong yuma-system module loaded'
yangcli-pro> end

feature-enabled

The feature-enabled function tests whether the specified YANG feature is enabled within the program.

boolean feature-enabled (module-name, feature-name)

Parameters:

  • Parameter 1:

    • Type: String

    • Usage: Mandatory

    • Purpose: Specifies the module name to check.

  • Parameter 2:

    • Type: String

    • Usage: Mandatory

    • Purpose: Specifies the YANG feature name defined within the module indicated by parameter 1.

Returns: Boolean

  • true: the specified feature is enabled

  • false: the specified feature is not enabled, possibly not known

Errors:

  • Missing parameter error if less than 2 parameters provided.

  • Extra parameters error if more than 2 parameters provided.

  • All unknown parameter values cause a 'false' result.

Example:

yangcli-pro> if "feature-enabled('mymodule', 'myfeature')"
yangcli-pro> log-info 'myfeature is enabled'
yangcli-pro> else
yangcli-pro> log-error 'myfeature is not enabled'
yangcli-pro> end

Error Reference

All YumaPro programs use the same set of error numbers and error messages.

Error numbers are 3 digit unsigned integers in the range 1 to 999. The number 0 is reserved for the NO_ERR constant, which is the same as the <ok/> status returned by the server.

The file ncx/status_enum.h contains the status_t enumeration typedef.

Error Number Types

range

description

0

no error

1

EOF

2 - 99

internal program errors

100 to 199

system errors

200 to 999

user errors

1000 to 1999

warnings

2000 to 2999

informational messages

Error Messages

The current list of error numbers and default error messages can be obtained with the yangdump-pro program --show-errors parameter. The enumerations for the The default error message can be replaced for some error conditions with the YANG "error-message" statement.

The following list shows the default error messages for all error numbers currently in use.


yangdump-pro 21.10-3 errors and warnings

  0	ok
  1	EOF reached
  2	NULL pointer
  3	malloc failed
  4	invalid internal value
  5	internal buffering failed
  6	invalid queue deletion
  7	wrong init sequence
  8	queue node not header
  9	queue node not data
 10	invalid queue header
 11	entry already queued
 12	too many entries
 13	libxml2 operation failed
 14	internal read-write lock error
 15	internal mutex error
 16	internal heap check error
 17	internal spin lock failed
 18	unspecified general error
100	cannot open file
101	cannot read file
102	cannot close file
103	cannot write file
104	cannot change directory
105	cannot stat file
106	buffer overflow error
107	cannot delete file
108	cannot access file
109	db connect failed
110	db entry exists
111	db not found
112	db query failed
113	db delete failed
114	wrong checksum
115	wrong tag type
116	db read failed
117	db write failed
118	db init failed
119	beep init failed
120	beep init nc failed
121	xml reader internal
122	open directory failed
123	read directory failed
200	no config file
201	no source file
202	POST read input
203	bad drive
204	bad path
205	bad filename
206	duplicate value pair
207	page not handled
208	page access denied
209	missing form params
210	invalid form state
211	duplicate namespace
212	xml reader start failed
213	xml reader read failed
214	wrong XML node type
215	xml reader null name
216	xml reader null value
217	xml reader wrong name
218	xml reader wrong value
219	xml reader wrong element
220	xml reader extra nodes
221	xml reader EOF
222	wrong length
223	entry exists
224	duplicate entry
225	not found
226	missing file
227	unknown parameter
228	invalid name
229	unknown namespace
230	wrong namespace
231	wrong data type
232	wrong value
233	missing parameter
234	extra parameter
235	empty value
236	module not found
237	max length exceeded
238	invalid token
239	unended quoted string
240	read failed
241	invalid number
242	invalid hex number
243	invalid real number
244	EOF reached
245	wrong token type
246	wrong token value
247	buffer overflow
248	invalid range
249	overlapping range
250	definition not found
251	definition segment not found
252	type not allowed in index
253	index type not found
254	type not mdata
255	meta-data not allowed
256	top not found
257	resource in use
258	invalid value
259	too big
260	missing attribute
261	bad attribute
262	unknown or unexpected attribute
263	missing element
264	bad element
265	unknown or unexpected element
266	unknown namespace
267	access denied
268	lock denied
269	resource denied
270	rollback failed
271	data exists
272	data missing
273	operation not supported
274	operation failed
275	partial operation
276	wrong namespace
277	wrong node depth
278	wrong owner
279	wrong element
280	wrong order
281	extra node
282	wrong node type
283	expecting complex node type
284	expecting string node type
285	wrong data type
286	wrong data value
287	invalid number length
288	value not in range
289	wrong number type
290	invalid enum value
291	value not in set
292	extra list string found
293	unknown object
294	extra parameter instance
295	extra case in choice
296	missing mandatory choice
297	wrong config state
298	unknown application
299	unknown data type
300	access control violation
301	config locked
302	wrong config state
303	max-access exceeded
304	wrong index type
305	wrong instance type
306	missing index component
307	config not found
308	extra attribute instance(s) found
309	required attribute not found
310	required value instance not found
311	extra value instance(s) found
312	target is read only
313	invalid pattern
314	wrong version
315	connect failed
316	unknown host
317	session failed
318	authentication failed
319	end of comment not found
320	invalid string concatenation
321	import not found
322	missing type sub-section
323	restriction not allowed for this type
324	specified refinement not allowed
325	definition loop detected
326	default case contains mandatory object(s)
327	import loop
328	include loop
329	expecting module
330	expecting submodule
331	undefined prefix
332	imported module has errors
333	pattern match failed
334	invalid data type change
335	mandatory object not allowed
336	unique-stmt test failed
337	max-elements exceeded
338	min-elements not reached
339	must-stmt test failed
340	data restriction violation
341	missing instance for insert operation
342	object not config
343	invalid conditional object
344	using obsolete definition
345	invalid augment target
346	duplicate refine sub-clause
347	invalid deviate sub-clause
348	invalid XPath expression syntax
349	invalid instance-identifier syntax
350	require-instance test failed
351	key or select attribute not allowed
352	invalid unique-stmt node
353	invalid duplicate import-stmt
354	invalid duplicate include-stmt
355	ambiguous command
356	unknown module
357	unknown version
358	value not supported
359	leafref path loop
360	variable not found
361	variable is read-only
362	decimal64 base number overflow
363	decimal64 fraction precision overflow
364	when-stmt tested false
365	no matches found
366	missing refine target
367	candidate cannot be locked, discard-changes needed
368	timeout occurred
369	multiple module revisions exist
370	XPath result not a nodeset
371	XPath node-set result is empty
372	node is protected by a partial lock
373	cannot perform the operation with confirmed-commit pending
374	cannot directly load a submodule
375	cannot write to a read-only object
376	cannot write to this configuration directly
377	YANG file missing right brace
378	invalid protocol framing characters received
379	base:1.1 protocol not enabled
380	persistent confirmed commit not active
381	multiple matches found
382	no schema default for this node
383	expected key leaf in list
384	top-level mandatory objects are not allowed
385	unknown resource
386	unended config line block
387	not supported in evaluation version
388	unknown resource instance
389	input data not expected
390	method not allowed
391	query parameter not allowed for method
392	edit pre-condition failed
393	header not allowed
394	running config has validation errors
395	binary file found instead of text file
396	module is imported by other modules
397	restricted module cannot be unloaded
398	request limit reached in evaluation version
399	IO select call failed
400	session dropped
401	media type not in range
402	an appropriate representation could not be found
403	data is not in a format acceptable for processing
404	unknown query parameter
405	missing Accept header
406	password is too short
407	missing input data
408	value disabled by if-feature-stmt
409	when-stmt not allowed on key leaf
410	if-feature-stmt not allowed on key leaf
411	invalid XML response would be returned
412	JSON encoding not yet supported
413	missing data definition statement
414	default value conditional on if-feature
415	invalid escape sequence in double-quoted string
416	invalid status for child node
417	configuration template not found
418	program is shutting down
419	notifications are not enabled
420	maintenance mode active
421	DSCP unavailable
422	encoding unsupported
423	filter unavailable
424	filter unsupported
425	insufficient resources
426	no such subscription
427	replay unsupported
428	stream unavailable
429	cannot exclude changes
430	datastore not subscribable
431	no such subscription resynch
432	on-change unsupported
433	on-change synch unsupported
434	period unsupported
435	update too big
436	sync too big
437	unchanging selection
1000	duplicate source
1001	include file not found
1002	invalid command line value
1003	invalid command line option
1004	command line option unknown
1005	invalid command line syntax
1006	missing command line value
1007	invalid form input
1008	invalid form
1009	no instance found
1010	session closed by remote peer
1011	duplicate import
1012	duplicate import with different prefix value
1013	local typedef not used
1014	local grouping not used
1015	import not used
1016	duplicate unique-stmt argument
1017	statement ignored
1018	duplicate include
1019	include not used
1020	revision date before 1970
1021	revision date in the future
1022	enum value order
1023	bit position order
1024	invalid status for child node
1025	duplicate sibling node name from external augment
1026	duplicate if-feature statement
1027	using deprecated definition
1028	XPath object predicate check limit reached
1029	empty XPath result in must or when expr
1030	no ancestor node available
1031	no parent node available
1032	no child node available
1033	no descendant node available
1034	no nodes available
1035	bad revision-stmt order
1036	duplicate prefix
1037	identifier length exceeded
1038	display line length exceeded
1039	received unknown capability
1040	invalid module capability URI
1041	unknown child node, using anyxml
1042	invalid value used for parm
1043	changing object type to string
1044	using a reserved name
1045	conf file parm already exists
1046	no valid revision statements found
1047	dependency file has errors
1048	top-level object is mandatory
1049	file name does not match [sub]module name
1050	unique-stmt component conditions do not match parent list
1051	reentrant call detected (retry)
1052	XPath compare value invalid for YANG type
1053	XPath comparing different YANG object types
1054	Revision date has already been used
1055	Non-config object referenced in config node XPath
1056	Mandatory nodes not allowed in external augments
1057	Self-referencing XPath expression