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.
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.
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.
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.
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.
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.
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.
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.
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
[email protected] (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:
exported symbols (--exports)
imported modules (--dependencies)
object identifiers (--identifiers)
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.