4  System Configuration

The YumaPro programs use YANG to define its configuration parameters.

The 'ncx:cli' extension is used within a container with the same name as the program to define all CLI parameters.  Some parameters are shared (see yuma-app-common.yang), so they are not located directly in the container.

 

 

container yangcli-pro {
ncx:cli;

// yangcli-pro CLI parameters defined as choices and leafs   here

}

 

 

The following YANG modules are provided, which contain all the configuration parameters for YumaPro:

 

Note:

 

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

  1. environment variables

  2. command line parameters

  3. configuration file

 

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

 

4.1.1  $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:  none

C shell example:

 


setenv HOME  /home/andy

 

Bash shell example:

 


export HOME=/home/andy

4.1.2  $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:  --yuma-home

CLI example:

 


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

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

4.1.4  $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.  Refer to the Command Line Parameter Reference for more details.  If --subdirs=false is used, then only the specified directory will be searched instead.

Note:  This parameter specifies the exact directory locations when searching for files.   This is different than the $HOME, $YUMAPRO_HOME, and $YUMAPRO_INSTALL environment variables, which specify a YumaPro root directory.

 

Default value:  none

CLI override:  --modpath

CLI example:

 


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

 

 

4.1.5  $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.  Refer to the Command Line Parameter Reference for more details.  If --subdirs=false is used, then only the specified directory will be searched instead.

Note:  This parameter specifies the exact directory locations when searching for files.   This is different than the $HOME, $YUMAPRO_HOME, and $YUMAPRO_INSTALL environment variables, which specify a YumaPro root directory.

 

Default value:  none

CLI override:  --loadpath

CLI example:

 


--loadpath=”$HOME/modules2”

 

C shell example:

 


setenv YUMAPRO_LOADPATH  “$HOME/modules2”

 

Bash shell example:

 


export YUMAPRO_LOADPATH=“$HOME/modules2”

 

 

4.1.6  $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.  Refer to the Command Line Parameter Reference for more details.  If --subdirs=false is used, then only the specified directory will be searched instead.

Note:  This parameter specifies the exact directory locations when searching for files.   This is different than the $HOME, $YUMAPRO_HOME, and $YUMAPRO_INSTALL environment variables, which specify a YumaPro root directory.

 

Default value:  none

CLI override:  --datapath

CLI example:

 


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

4.1.7  $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.  Refer to the Command Line Parameter Reference for more details.  If --subdirs=false is used, then only the specified directory will be searched instead.

Note:  This parameter specifies the exact directory locations when searching for files.   This is different than the $HOME, $YUMAPRO_HOME, and $YUMAPRO_INSTALL environment variables, which specify a YumaPro root directory.

 

Default value:  none

CLI override:  --runpath

CLI example:

 


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

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

 

 

/usr/share/yang/modules

 

 

~/modules/test/test.yang

 

 

~andy/modules/test/test.yang

~fred/scripts

 

 

$WORKDIR/tests/test-all-interfaces

$YUMAPRO_HOME/data/startup-cfg.xml

 

 

 

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

The following environment variables affect file searches:

The following configuration parameters affect file searches:

 

4.2.1  YumaPro Work Directory

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

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.

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

 

  1.  

    --module=test.yang
    --module=../more-modules/test3@2009-04-01.yang

 

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.

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

 

 

// file foo.2009-01-15.yang

module foo {

 

   namespace “http://example.com/ns/foo”;

   prefix foo;

 

   // rest of header follows

 

   revision 2009-01-15 {

 description “Initial version.”;

   }

 

   // rest of module follows

}

 

 

If the file is not found, or the most current revision date is not correct, then the module search is repeated for 'foo.yang'.  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.

 

 

// file foo.yang

module foo {

 

   namespace “http://example.com/ns/foo”;

   prefix foo;

 

   // rest of header follows

 

   revision 2009-01-15 {

 description “Initial version.”;

   }

 

   // rest of module follows

}

 

 

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.

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

4.2.4  File Search Paths

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

 

Module Search Path

 

 

--module=../test.yang

 

 

--module=foo

 

    1.  

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

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

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

    1. The $HOME/modules directory is checked.

    1. The $YUMAPRO_HOME/modules directory is checked.

    1. The $YUMAPRO_INSTALL/modules directory is checked.

 

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.

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

  4. The $HOME/data directory 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.

  5. The $YUMAPRO_HOME/data directory 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.

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

  7. The $YUMAPRO_INSTALL/data directory 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.

  8. The /usr/share/yumapro/data directory 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.

  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.  

  1. The $HOME/scripts directory is checked.

  1. The $YUMAPRO_HOME/scripts directory is checked.

  1. The $YUMAPRO_INSTALL/scripts directory is checked.

4.3  Configuration Files

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

graphics11

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.

 

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

 

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.

 

// file startup-cfg.xml

 

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

 

 

4.3.2  Text Configuration Files

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

 

# this is a comment

log-level info     # this is also a comment

 

 

 

this is a command line

this is the start \

of a long \

three line command

this is a new command

 

 

yangdump-pro {

   # set some display control parameters

   log-level debug2

   warn-linelen 72

   indent 4

}

 

 

ifStackEntry  11 42 {

# the key leafs will also printed here

ifStackHigherLayer 11

ifStackLowerLayer 42

ifStackStatus active

}

 

 

// test.conf

yangdump-pro {

# common yangdump-pro parameters here

}

 

yangdiff-pro {

# common yangdiff-pro parameters here

}

 

 

4.3.3  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

}

 

 

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)"
}

 

4.4  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”):

 

These keywords may be specified to the log-level command, either via the command line (see bootstrap CLI below) or the 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:

4.4.1  Logging Output Stream Commands

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

4.4.2  Logging Detail Commands

 

4.4.3  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.  Note: backtrace-related functionality is not supported by Windows or Mac versions of the software at this time.

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). Specific requirements are described int the Using Backtrace Information section below.

4.4.4  Logging Examples

Note: 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 processsing. 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.

 

Refer to the YumaPro CLI Reference for more details. on these configuration parameters.

 

4.4.5  Logging Backtrace Information

Under special circumstances, YumaWorks customer support may request that an image be run with the --log-backtrace enabled for trouble-shooting purposes. In such a case, the resulting log file would be forwarded to YumaWorks for analysis.

For source code development customers only, it is possible to cut and paste information from the output of the --log-backtrace command directly into the  gdb debugger in order to construct a symbolic stack trace corresponding to the output of a given log message. Note that at the present time, a statically linked image containing debug symbols must be used. Consider the following example:

 

   mydir> netconfd-pro --superuser=user1 --log=log-001.log \

--log-header=”custom localtime”    \

--log-backtrace=0 --log-level=debug

 

 

[2012-10-11 17:46:59] [warn] Warning: SIL code for module 'test-xxx' not found

--Backtrace: [0x427f7b][0x430fa6][0x43a02b][0x434c8a][0x42a06d][0x41aca7][0x41ae28][0x7f8a0656476d][0x41a799]

 

 

 

   mydir> gdb /usr/sbin/netconfd-pro

 

 

 mydir> gdb /usr/sbin/netconfd-pro

 

GNU gdb (Ubuntu/Linaro 7.4-2012.04-0ubuntu2) 7.4-2012.04

Copyright (C) 2012 Free Software Foundation, Inc.

License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>

This is free software: you are free to change and redistribute it.

There is NO WARRANTY, to the extent permitted by law.  Type "show copying"

and "show warranty" for details.

This GDB was configured as "x86_64-linux-gnu".

For bug reporting instructions, please see:

<http://bugs.launchpad.net/gdb-linaro/>...

Reading symbols from /usr/sbin/netconfd-pro...done.

(gdb) list *0x427f7b

0x427f7b is in load_invoke (agt_ncx.c:2938).

2933                                    (revval) ? VAL_STR(revval) : NULL,

2934                                    TRUE);

2935            if (res == ERR_NCX_SKIPPED) {

2936                log_warn("\nWarning: SIL code for module '%s' not found",

2937                         VAL_STR(modval));

2938                res = ncxmod_load_module(VAL_STR(modval),

2939                                         (revval) ? VAL_STR(revval) : NULL,

2940                                         &agt_profile->agt_savedevQ,

2941                                         &mod);

2942            } else if (res == NO_ERR) {

(gdb) list *0x430fa6

0x430fa6 is in agt_rpc_dispatch (agt_rpc.c:1617).

1612     * especially since the return of data can be automated

1613     * in the send_rpc_reply phase.

1614     */

1615    if ((res==NO_ERR) && cbset && cbset->acb[AGT_RPC_PH_INVOKE]) {

1616        msg->rpc_agt_state = AGT_RPC_PH_INVOKE;

1617        res = (*cbset->acb[AGT_RPC_PH_INVOKE])(scb, msg, &method);

1618        if (res != NO_ERR) {

1619            /* make sure there is an error recorded in case

1620             * the invoke phase callback did not add one

1621             */

(gdb) list *0x43a02b

0x43a02b is in agt_top_dispatch_msg (agt_top.c:153).

148

149    /* check node type and if handler exists, then call it */

150    if (top.nodetyp==XML_NT_START || top.nodetyp==XML_NT_EMPTY) {

151        /* find the owner, elname tuple in the topQ */

152        handler = top_find_handler(top.module, top.elname);

153        if (handler) {

154            /* call the handler */

155            (*handler)(scb, &top);

156        } else {

157            res = ERR_NCX_DEF_NOT_FOUND

 

4.4.6  Logging Hints

This section will be expanded over time as tips and best practices information emerges from the field.

  1. Log Message Interleaving

By directing the logging output of potentially multiple instances of yangcli-pro and netconfd-pro to syslog, message activity between different instances may be captured and reported in a single chronological  history.

 

 

4.5  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. (See the --max-sessions parameter as described in the Netconfd-Pro manual for more information on this.) 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.)

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 thead/session ids:

Note that one should never see the same session id with two different thread ids, unless the old session was closed or killed (see close-session and kill-session commands in the Yangcli-Pro manual) and a new session created that reused the old session id.

 

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

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:

Refer to the YumaPro CLI Reference for more details. on these configuration parameters.

 

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

 

4.7.1  Parameter Syntax

A CLI parameter has 2 forms:

 

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

 

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

 

4.7.3  ncx:default-parm 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.

If no parameter name is found when processing CLI parameter input, and the ncx:default-parm  extension is present in the container or RPC input being processed, then the specified parameter name will be used instead of generating an error.  The value must be valid for the parameter syntax, according to its YANG definition.  This means that for the default parameter, only the <value> component of the complete parameter syntax may be used, as well as the normal forms.

 

 

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.

Note: 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=.

 

 

These commands are equivalent in the yangdump-pro program.