Yuma User Manual

 

 

 

YANG-Based Unified Modular Automation Tools

 

 

Common User Manual

 

Version 2.2

 

Last Updated January 26, 2012

Table Of Contents

Yuma User Manual

1 Preface        3

1.1 Legal Statements        3

1.2 Additional Resources        3

1.2.1 WEB Sites        3

1.2.2 Mailing Lists        4

1.3 Conventions Used in this Document        4

2 Summary        5

2.1 What is Yuma?        5

2.2 Intended Audience        6

3 Introduction        7

3.1 System Components        7

3.1.1 YANG        9

3.1.2 NETCONF        11

3.1.3 YANG-based Automation        14

3.1.4 YANG Language Extensions        19

3.1.5YANG Compiler        20

3.1.6 YANG Module Library        20

3.1.7 YANG Files        23

3.1.8 NETCONF Managers        23

3.1.9 NETCONF Agents        23

4 System Configuration        25

4.1 Environment Variables        25

4.1.1 $HOME        26

4.1.2 $YUMA_HOME        26

4.1.3 $YUMA_INSTALL        27

4.1.4 $YUMA_MODPATH        27

4.1.5 $YUMA_DATAPATH        28

4.1.6 $YUMA_RUNPATH        29

4.2 Searching for Files        29

4.2.1 Yuma Work Directory        31

4.2.2 Parameter Searches        31

4.2.3 Import/Include Searches        32

4.2.4 File Search Paths        33

4.3 Configuration Files        35

4.3.1 XML Configuration Files        36

4.3.2 Text Configuration Files        37

4.4 Bootstrap CLI        39

4.5 Configuration Parameters        39

4.5.1 Parameter Syntax        39

4.5.2 ncx:cli Extension        40

4.5.3 ncx:default-parm Extension        40

5 XPath Reference        41

5.1 XPath 1.0        42

5.1.1 XML Namespaces        42

5.2 YANG Specific XPath Behavior        43

5.3 Custom XPath Variables        43

5.3.1 user        43

5.4 Custom XPath Functions        43

5.4.1 module-loaded        43

5.4.2 feature-enabled        44

6 Error Reference        46

6.1 Error Messages        46

 

1 Preface

1.1 Legal Statements

Copyright 2009 - 2012,  Andy Bierman,  All Rights Reserved.

1.2 Additional Resources

This document assumes you have successfully set up the software as described in the printed document:

        Yuma  Installation Guide

 

Other documentation includes:

 Yuma Quickstart Guide

        Yuma netconfd Manual

 Yuma  yangcli  Manual

        Yuma  yangdiff Manual

 Yuma yangdump Manual

        Yuma Developer Manual

 

To obtain additional support you may join the yuma-users group on sourceforge.net and send email to this e-mail address:

        yuma-users@lists.sourceforge.net

The SourceForge.net Support Page for Yuma can be found at this WEB page:

        http://sourceforge.net/projects/yuma/support

 

There are several sources of free information and tools for use with YANG and/or NETCONF.

The following section lists the resources available at this time.

1.2.1 WEB Sites

1.2.2 Mailing Lists

1.3 Conventions Used in this Document

The following formatting conventions are used throughout this document:

Documentation Conventions

Convention

Description

--foo

CLI parameter foo

<foo>

XML parameter foo

foo

yangcli command or parameter

$FOO

Environment variable FOO

$$foo

yangcli global variable foo

some text

Example command or PDU

some text

Plain text

2 Summary

 

2.1 What is Yuma?

Yuma is a set of programs providing a complete network management system and development environment, which implements the following standards:

The following programs are included in the Yuma suite:

 

Although any arbitrary YANG file can be automatically supported by Yuma, the following content (YANG modules) is built into the netconfd server, and supported by the yangcli client:

 

2.2 Intended Audience

This document is intended for users of the programs in the Yuma suite.

It contains the following information:

3 Introduction

The Yuma 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.

3.1 System Components

 

 

The following external program is used by Yuma, and needs to be pre-installed:

The following external libraries are used by Yuma, and need to be pre-installed. They are usually installed by default and do not need to be installed by you:

 

The following external library is built within Yuma and does not need to be pre-installed:

The following shared (or static) library is built by Yuma and used by almost all of its programs:

The following libraries are built by Yuma, and used within executables:

The following binaries are built by Yuma:

The following sample netconfd module instrumentation library is provided as an example.  These libraries (e.g., libfoo.so) can only be created with the Yuma SDK.  Refer to the Yuma Developer's Guide for details on creating server instrumentation libraries.

3.1.1 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 programmatic interface utilizing all protocol features:

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.

YANG provides complex nested data structures and choices, which allows data modelers to design management interfaces which closely resemble the native data structures within the server implementation.

It is easy to get started with YANG, and there are many optional advanced features that can be utilized as well.  YANG provides many machine-readable constructs which allow Yuma to automate many aspects of network management software development.

 

A YANG module can be a single file, or it can be split into an arbitrary number of files, using sub-modules.  A YANG submodule is essentially the same as a main module, except that the namespace URI value is shared between the main module and all its submodules.

A submodule is referenced with the include statement instead of the import statement.

Submodules can also include other submodules, except a loop may not be formed by the include statements.

Conceptually, the module is not nested.  All definitions in submodules appear at the top level of the YANG module, even submodules included by other submodules.

All YANG modules and submodules have revision dates.  The example shows a simple version number, but the actual revision strings are date strings in the form 'YYYY-MM-DD'.

Yuma programs support concurrent usage of different revisions of the same module or submodule.  This can occur via groupings from external modules within the YANG language.  Only one revision of a module can be imported into a single module or submodule, but any of these files may in turn import other modules.  It is possible that a different version of the same module could be indirectly imported in this case.

Deviation modules are normal YANG modules, except they only contain deviation statements.  These deviation statements are used to alter (patch) the YANG modules with implementation-specific differences.

A deviation module can contain any number of deviation statements, and they can apply to an arbitrary number of objects, from any module.  Multiple deviation statements for the same target will be combined by the server before using them, and all deviate statements for the same object will be validated together, as if they were all contained in the same deviation statement.  The order of the deviation statements is irrelevant.

Deviations modules are processed first, and the deviation statements save for later.  The import statements are ignored, unlike real module processing.

Since deviation modules are not identified in any way, Yuma programs use the --module parameter to refer to a normal YANG module or submodule, and the --deviation parameter to refer to a deviation module.

 

 

The YANG feature statement is used to define a conceptual partition within the module.

Objects that contain the if-feature statement for the corresponding feature are part of the feature.

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.

Multiple if-feature statements form a logical AND expression.  All the referenced features must be enabled for the object to be available.  In the example above, leaf 'YY2' is not present unless feature A and B are both advertised by the server.

3.1.2 NETCONF

The mandatory components of the NETCONF protocol are defined in RFC 4741 and RFC 4742.

 

 

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.