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:

Environment Variables
Command Line Parameters
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:

searches on behalf of configuration parameters
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:

$HOME
$YUMAPRO_HOME
$YUMAPRO_MODPATH
$YUMAPRO_LOADPATH
$YUMAPRO_DATAPATH
$YUMAPRO_RUNPATH

The following configuration parameters affect file searches:

YumaPro Search Root?

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.

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

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

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.

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.
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.
The current working directory is checked. No sub-directories are checked, if any are present
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.
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.
The $HOME/.yumapro directory is checked.
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.
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.
The /etc/yumapro directory is checked.

Script Search Path

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

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.
The current working directory is checked. No sub-directories are checked, if any are present.
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.
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.
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.
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.

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:

--indent
--with-defaults

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
- --indent
- --with-defaults
- --display-mode

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 [email protected] 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:

prefix: consists of 0, 1, or 2 consecutive dash characters.
parameter name: name of the parameter. A partial name may be used if it is unique.
separator: either consists of the 'equals sign' character ('='), which may be preceded or followed by whitespace, or just whitespace with no equals sign character.
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=.