Yuma yangcli Manual

YANG-Based Unified Modular Automation Tools

NETCONF Over SSH Client

Version 1.15

Last Updated:  July 20, 2011

Table Of Contents

1 Preface

1.1 Legal Statements

Copyright 2009 - 2011 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 User Manual

Yuma  netconfd  Manual

Yuma  yangdiff Manual

Yuma yangdump Manual

Yuma Developer Manual

To obtain additional support you may send email to this e-mail address:

andy@netconfcentral.org

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

• Netconf Central

  • http://www.netconfcentral.org/

  • Yuma Home Page

    • Free information on NETCONF and YANG, tutorials, on-line YANG module validation and documentation database

• Yuma SourceFource OpenSource Project

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

    • Download Yuma source and binaries; project forums and help

• Yang Central

  • http://www.yang-central.org

  • Free information and tutorials on YANG, free YANG tools for download

• NETCONF Working Group Wiki Page

  • http://trac.tools.ietf.org/wg/netconf/trac/wiki

  • Free information on NETCONF standardization activities and NETCONF implementations

• NETCONF WG Status Page

  • http://tools.ietf.org/wg/netconf/

  • IETF Internet draft status for NETCONF documents

• libsmi Home Page

  • http://www.ibr.cs.tu-bs.de/projects/libsmi/

  • Free tools such as smidump, to convert SMIv2 to YANG

1.2.2 Mailing Lists

• NETCONF Working Group

  • http://www.ietf.org/html.charters/netconf-charter.html

  • Technical issues related to the NETCONF protocol are discussed on the NETCONF WG mailing list.  Refer to the instructions on the WEB page for joining the mailing list.

• NETMOD Working Group

  • http://www.ietf.org/html.charters/netmod-charter.html

  • Technical issues related to the YANG language and YANG data types are discussed on the NETMOD WG mailing list.  Refer to the instructions on the WEB page for joining the mailing list.

1.3  Conventions Used in this Document

The following formatting conventions are used throughout this document:

Documentation Conventions

2 yangcli User Guide

Program Components

2.1 Introduction

The yangcli program is a NETCONF over SSH client application.  It is driven directly by YANG modules, and provides a simple but powerful application interface for any YANG file.   There is no configuration required at all to use any YANG file, although there are some YANG extensions that will be utilized if present.

2.1.1 Features

The yangcli client has the following features:

• Automatic support for all NETCONF protocol operations, including several 'short-hand' commands for the most common operations, like <edit-config> and <get-config>.

• Automated database locking, unlocking and error cleanup, using the high-level get-locks and release-locks commands.

• Automatic, standards-based, server schema synchronization, using the YANG module capability URI information in the <hello> PDU, and the <get-schema> operation:

  • For each session, the exact view of the server schema definition tree is created, based on the module capability:

    • module namespace

    • module name

    • module revision date

    • enabled features

    • names of any modules that contain deviations for this module

  • The help text and parameter validation for each session will be tailored to the capabilities advertised by the server.

  • Parses each potential matching YANG file to make sure the module name, revision date, and namespace URI value are all exactly the same as the values in the module capability URI.

• Understands all NETCONF protocol capabilities, and complex hard-wired logic simplifies protocol usage, and allows high-level commands to pick appropriate defaults for many RPC operation parameters.

• Load any YANG module at boot-time or run-time and start using it immediately.

• Full concurrent support for multiple revisions of the same module.

• Supports NETCONF notifications, including :interleave capability.

• Full XPath 1.0 and subtree filtering support.

• Automatic support for all YANG language mechanisms, including extensions.

• Any YANG <rpc> operation is automatically available as a yangcli command.

• Uses YANG files directly as input, so no pre-processing or configuration needed to use a new module.

• Can be called from unix scripts in 'batch-mode' to automatically establish a NETCONF session, issue a command or invoke a yangcli script, close the session, and return the results.

• Extensive interactive shell environment, including user variables, file variables, smart parameter set completion, and a simple scripting environment for automatic operation.

• Automatic, context-sensitive (tab key) command-line completion.

• Full support for XPath, instance-identifier, leafref, and identityref parameters.

• Automatic, context-sensitive help system, based completely on YANG files and using the exact modules supported by the current NETCONF session, if connected.

• Full, customizable command line editing, using emacs by default, but vi or a custom set of keystroke bindings are also supported.

• Command line history and command recall.

• Store and recall command line history files for later use.

• Automatic NETCONF session management, including support for all YANG extensions to the <capability> element.

• Automatic recognition and support for all NETCONF 'capability' related operations.

• Automatic support for all YANG additions to the NETCONF protocol, such as the insert operation

• Unlimited nested scripts with up to 10 parameters each can automate testing and other management tasks

2.1.2 Starting yangcli

The current working directory in use when yangcli is invoked is important.  It is most convenient to run yangcli from a work directory, rather than the installation directory or within the module library.

The yangcli program can be invoked several ways:

• To get the current version and exit:

   

yangcli --version

•  

• To get program help and exit:

   

yangcli --help

yangcli --help --brief

yangcli --help --full

•  

• To start an interactive session with the default parameters:

   

yangcli

•  

• To start an interactive session with a new log file:

   

yangcli --logfile=mylogfile

•  

• To start an interactive session and append to an existing log file:

   

yangcli -- logfile =mylogfile --log-append

•  

• To get parameters from a configuration file:

   

yangcli --config=~/yangcli.conf

•  

• To begin to connect to a server upon startup, provide the --server parameter. The connect command will be started upon startup and the user will be prompted to enter the rest of the mandatory parameters to the connect command.

   

yangcli server=myserver.example.com

•  

• To connect to a server and automatically connect without any interactive interruption, enter the --server , --user , and --password parameters. A session startup will be attempted right away, using these parameters.  Any optional parameters for the connect command ( --port or --timeout ) may be entered as well.  All parameters can be entered from a config file, and/or the command line.

   

yangcli --server=myserver.example.com \

--user=andy --password=yangrocks

•  

• To automatically connect to a server, run a script in non-interactive mode, and then remain connected to the server, add the --run-script parameter to the connection parameters.  The --runpath parameter can also be entered, if needed.

   

yangcli --server=myserver.example.com \

--user=andy --password=yangrocks \

--run-script=mytestscript

•  

• To automatically connect to a server, run a script in non-interactive mode, and then exit the program, add the --batch-mode and --run-script parameters to the connection parameters. The  --runpath parameter can also be entered, if needed.

   

yangcli --server=myserver.example.com \

--user=andy --password=yangrocks \

--run-script=mytestscript --batch-mode

•  

• To automatically connect to a server, and run a single command instead of a script, and then exit, use the --run-command parameter instead of the --run-script parameter.  The --batch-mode parameter can be left out to remain in the current session (in interactive mode) after the command is invoked.

yangcli --server=myserver.example.com \

--user=andy --password=yangrocks \

--batch-mode --run-command=”sget /system”

2.1.3 Stopping yangcli

To terminate the yangcli program, use the quit command.

The control-C character sequence will also cause the program to be terminated.

2.1.4 Statements

The yangcli script interpreter accepts several types of statements:

yangcli Statements

A command can be as simple like 'get' or complex, like 'edit-config'.

A variable assignment sets the specified user or system variable to the right hand side of the expression.  An expression has many forms, including the result from a local command or a remote NETCONF operation.

If a string that matches a command is used as the assignment value, then it must be entered in quotes (single or double).  For example, the $$default-operation system configuration variable accepts enumeration values which also match RPC commands:

yangcli> $$default-operation = 'merge'

A file assignment is essentially the same as a variable assignment, except the right hand side of the expression is saved in the specified file, instead of a user variable.

To delete a user variable, leave the right hand side of the expression empty (or just whitespace).

Note: More statement types will be available in the next release.

2.1.5 Commands

The yangcli program has several built-in commands, defined in yangcli.yang, yuma-netconf.yang, and notifications.yang.

The YANG rpc statement is used to define the syntax and behavior of each command.

There are 2 types of yangcli commands:

• local:  the command is executed within the yangcli application, and can be invoked at any time.

• remote: the command is executed on the remote server, and is only available when a NETCONF session is active.  Any YANG rpc statement that yangcli does not recognize as a local command is treated as a remote command available on the server.

Local Commands

The following table shows the standard NETCONF protocol operations that are directly available for use, depending on the capabilities of the server.

Standard NETCONF Commands

The following yangcli commands are available for simplified access to standard NETCONF operations

Custom NETCONF Commands

The following table shows the extended NETCONF protocol operations that are available on the netconfd server only.

Extended netconfd Commands

2.1.6 Variables

The yangcli program utilizes several types of user-accessible variables.  These variables can be listed with the 'show vars' command and other commands as well.

A variable reference consists of 1 or 2 dollar signs ('$'), followed immediately by a valid identifier string (e.g., $$global-log or $local-log).

Variables can be 1 or more characters in length, and follow the YANG rules for identifier names.  The first character must be a letter,  'A' to 'Z', or 'a' to 'z'.  The 2nd to last characters can be a letter 'A' to 'Z', or 'a' to 'z', number ('0' to '9'), an underscore ('_'), a dash ('-'), or a period ('.')  character.

There are 4 categories of parameters supported:

1. Read-only system variables

2. Read-write system variables

3. Read-write global user variables

4. Read-write local user variables

It is an error if a variable is referenced (in the right-hand-side of a statement) that does not exist.

The first 3 types are global variables, which means that they are available to all run-levels of all scripts.  The last type, called a local variable, is only visible to the current run-level of the current script (or interactive shell).  Refer to the following section for more details on run levels.

Variable Syntax

The following table shows the unix environment variables that are available as read-only global variables in yangcli.  These variables are set once when the program is started, and cannot be used in the the left hand side of an assignment statement.

Read-only system variables

The following table shows the CLI configuration parameters that can be read or changed (but not deleted).  If a particular parameter was not set during program invocation, then the associated variable will contain the empty string.

Read-write system variables

Read-write global user variables

If a unrecognized global variable (e.g., $$foo) is used in the left-hand side of an assignment statement, then a global user variable will be created with that name.  If the global user variable already exists, then its value will be overwritten.

Read-write local user variables

If a local variable (e.g., $foo) is used in the left-hand side of an assignment statement, then a local user variable will be created with that name.  If the local user variable already exists, then its value will be overwritten.  If the variable is created within a script (i.e., run-level greater than zero), then it will be deleted when the script exits.

2.1.7 Files

File contents can be used in yangcli statements, similar to user variables.

A file reference consist of the 'at-sign' character ('@') followed immediately by a valid file specification.

@foo.yang = get-schema --identifier=foo --version=”” --format=”YANG”

mgrload --module=foo

If the file extension is “.yang”, “.log”, “.txt”, or “.text”, then the value (or command output) will be saved, and yangcli will strip off the outermost XML (if needed) to save the requested file as a pure text file.  Otherwise, the file will be saved in XML format.  The display mode set by the user can affect XML output.  If the display mode i s'xml-nons' then XML without namespace (xmlns) attributes will be generated instead of normal XML.

Note: The --display-mode configuration parameter, and $$display-mode system variable, only affect the output and display of data in the yangcli program.  NETCONF protocol messages are always sent in 'xml' mode.

Files may also be used as parameter replacements, within a command.

$saved_get = get --filter=@filter.xml --with-defaults=explicit

It is an error if the file referenced does not exist or cannot be read.

2.1.8 Scripts

Any command can be entered at the interactive shell, or stored in a script file, and invoked with the 'run' command.  Scripts are simply text files, and the extension used does not matter.

There are no formal templates for scripts, like there are for RPC operations, at this time.  Instead, positional parameters can be passed to any script.

The parameters named --P1 to --P9 allow up to 9 parameters to be passed to any script.  Within each script, the numbered parameters '$1' to '$9' are available, and contain the value that was passed as the corresponding  ---Pn” parameter when calling the script.

If a line contains only optional whitespace, followed by the pound sign character '#', then the line is treated as a comment.  These lines will be skipped.

If an error occurs during a command within a script, or an <rpc-error> is received from the server during a NETCONF session, then the running script will be canceled, and if this was a nested script, then all parent scripts will also be canceled.

Script Example:

run connect --P1=andy --P2==localhost --P3=yangrocks

// connect script

# start a NETCONF session

$user = $1

$server = $2

$password = $3

connect --user=$user --server=$server --password=$password

Run Levels

The run command can appear in a script.

When yangcli starts up, either in interactive mode or in batch mode, the script interpreter is at run level zero.  Each time a run command is invoked, either at the command line or within a script currently being invoked, a new run level with the next higher value is assigned.  Local variables are only visible within the current run level.

A maximum of 512 run levels are supported in yangcli.

Scripts can be called recursively, but a stop condition needs to be used to break the recursion (e.g., call the script from within a conditional code block.

Conditional Command Blocks

The 'if', 'elif', 'else', and 'end' commands are used to create an 'if command sequence'.

Any other commands that appear between these commands are part of a conditional command block.

These blocks can be nested.  The current conditional state is inherited, so an if command sequence within a false conditional block will not be executed.  A block can contain zero or more command lines,

These command work exactly like an 'if' expression within a program language such as Python.  Note that indentation is not significant, but it may be used to make scripts more readable.

The 'if' command starts a new if-command sequence.  It is followed by a conditional command block.  This block ends when an 'elif', 'else', or 'end' command within the same if command block is encountered.

At most, only one conditional code block within the if command sequence will be executed.  Once a conditional command block has been exectuted, any remaining blocks will be skipped.

All user and system variables that are available to the current script run level can be used within the XPath expressions for determining the conditional block state (true or false).

Conditional Command Loop Blocks

The 'while' and 'end' commands are used to create an 'while loop sequence'.

Any other commands that appear between these commands are part of a conditional command loop block.

These blocks can be nested.  The current conditional state is inherited, so a while loop sequence within a false conditional block will not be executed.  A block can contain zero or more command lines,

The loop condition can be a constant expression.  The maxloops parameter will prevent infinite looping, and can be utilized to use the while loop sequence as a simple 'for' loop, iterating a specific number of times.

All user and system variables that are available to the current script run level can be used within the XPath expressions for determining the conditional block state (continue or terminate loop).

Sample Script

The following script does not do any useful work.

It is provided to demonstrate some simple constructs.

$x = 0

while '$x < 2'

  # this is a comment

  log-info 'start 1'

  $x = eval '$x + 1'

  $y = 0

  while '$y < 4'

    log-info 'start 2'

    $y = eval '$y + 1'

    if "module-loaded('test')"

      log-info 'module test loaded'

    elif '$x > 1'

      log-info 'x>1'

    elif "feature-enabled('test3', 'feature1')"

      log-info 'feature1'

    else

      log-info 'else'

    end

    log-info 'end 2'

  end

  log-info 'end 1'

end

if "feature-enabled('test5', 'feature-foo')"

  log-info 'feature-foo'

  run add-foo-parms

end

2.1.9 Configuration Parameter List

The following configuration parameters are used by yangcli.  Refer to the CLI Reference for more details.

yangcli CLI Parameters

2.2 Invoking Commands

Commands can be entered with parameters:

• in one continuous line

   

  • merge target=/toaster/toastControl --value=”down”

   

• in several lines (using line continuation)

   

  • merge target=/toaster/toastControl \
    --value=”down”

   

• interactively prompted for each parameter

   

  • merge

    (will be prompted for target and value)

   

• a combination of the above

   

  • merge target=/toaster/toastControl

    (will be prompted for value)

When a command is entered, and the yangcli script interpreter is running in interactive mode (--batch-mode not active), then the user will be prompted for any missing mandatory parameters.

If the --optional parameter is present (or the $$optional system variable is set to 'true'), then the user will be prompted for any optional parameters that are missing.

A command has the basic form:

<name (QName)>  <parameter (any YANG type)>*

The command name is a qualified name matching the name used in the YANG rpc statement.  This is followed by zero or more parameters (in any order).

A command parameter has the same syntax as a CLI configuration parameter.

The command name syntax is described below.

An un-escaped end-of-line character ('enter key') terminates command line input.

2.2.1 Command Prompt

The yangcli command prompt changes, depending on the context.

Idle Mode:

If the script interpreter is idle and there is no NETCONF session active, then the prompt is simply the program name:

yangcli>

If the script interpreter is idle and there is a NETCONF session active, then the prompt is the program name, followed by ' <user>@<server>', depending on the parameters used in the connect command:

yangcli andy@myserver>

Continuation Mode:

If a backslash, end-of-line sequence ended the previous line, the prompt will simply be the word 'more' indented 3 spaces:

yangcli andy@myserver> get \

  more>

The 'more>' prompt will continue if the new line also ends in with an escaped end-of-line.  When a new line is finally terminated, all the fragments are spliced together and delivered as one command line.

Note: context-sensitive command completion is not available in this mode.

Choice mode:

If a partial command has been entered in interactive mode, and the script interpreter needs to prompt for a YANG 'choice' parameter, then a list of numbered cases will be presented, and the prompt will be the same as it was before (depending on whether a NETCONF session is active or not), except a colon character (':'), followed by the command name, will be added at the end.  As long as parameters for the same command are being entered (i.e., prompted for child nodes within a selected case, the command name will be appended to the prompt.

yangcli andy@myserver> sget

Enter a number of the selected case statement:

  1: case varref:

       leaf varref

  2: case from-cli:

       leaf target

       leaf optional

       anyxml value

Enter choice number [1 - 2]:

yangcli andy@myserver:sget>

Parameter mode:

If a partial command has been entered in interactive mode, and the script interpreter needs to prompt for a leaf or leaf-list, then the parameter name will appear in angle brackets ('<' and '>').

Filling mandatory case /sget/input/from/from-cli:

Enter string value for leaf <target>

yangcli andy@myserver:sget>

If the 'ncx:password' extension is part of the YANG definition for the leaf or leaf-list, then the characters entered at the prompt in this mode will not be echoed, and they will not be saved in the command history buffer.  Any default value will not be printed either.  Instead, 4 asterisks '****' will be printed, even though the correct value will be used in the command.

If a default value is available, it will appear in square brackets ('[' and ']'). In this case, entering 'return' will not be interpreted as an empty string, but rather the default value that was presented.

yangcli> connect

Enter string value for leaf <user> [andy]

yangcli:connect>

Enter string value for leaf <server> [myserver]

yangcli:connect>

Enter string value for leaf <password> [****]

yangcli:connect>

Enter uint16 value for leaf <port> [830]

yangcli:connect>

Enter uint32 value for leaf <timeout> [30]

yangcli:connect>

Note:  After a NETCONF session is terminated for any reason, the connection parameters will be remembered , and presented as defaults the next time the connect command is entered.

False Conditional Block Mode

If a conditional command (if, elif, else, or while command) is active, but the conditional expression is false, then any commands defined within that conditional block will not be executed.  If this occurs in interactive mode instead of a script, the string '[F]' will be added to the command prompt.  Note that the 'help' and 'log-info' commands do not get executed in the following example:

yangcli> if 0

yangcli[F]> help

yangcli[F]> log-info 'this will not get printed'

yangcli[F]> end

yangcli>

2.2.2 Command Name

The command name can be entered with or without an XML prefix:

yangcli andy@myserver> nc:get

yangcli andy@myserver> get

If there is a prefix (e.g., 'nc:get'), then it needs to be one of the XML prefixes in use at the time.   Use the 'show modules' command to see the modules and prefixes in use.  The YANG prefix will usually be the same as the XML prefix, but not always.

XML prefixes are required to be unique, so if any 2 YANG modules pick the same prefix, then 1 of them has to be changed for XML encoding purposes.

If the --default-module configuration parameter (or $$default-module system variable) is set, it will be used to resolve a command name without any prefix, if it is not a NETCONF or yangcli command.

An error message will be printed if the command entered cannot be found in any YANG module, or if there are multiple commands that match the same string.

2.2.3 ncx:default-parm Extension

Each command may define a default parameter, by placing an 'ncx:default-parm' extension in the rpc input section in the YANG rpc statement.  This extension allows less typing in yangcli to accomplish the same thing.

If the script interpreter encounters a string in the command line that is not a recognized parameter for that command, and there is a default parameter defined, then the string will be used as a value for the default parameter.

For example, the 'show' parameter is the default parameter for the 'history' command, so both of these commands will be interpreted to mean the same thing:

history --show=10
history 10

Note: the default parameter does not allow the wrong form of a parameter type to be entered, to accept the default for that parameter.  For example, the 'show' parameter above has a default value of '25':

# this is the same as history show=25

history

# this is an error, not the same as the above

history show

The following table shows the default parameters that are available at this time.

Default Parameters

2.2.4 Parameter Mode Escape Commands

There are 4 escape sequence commands that can be used while entering parameters.

They all begin with the question mark character ('?'), and end with the 'Enter' key.

Control key sequences are not used because that would interfere with command line editing keys.

Parameter mode escape sequences

Note: If the current parameter is considered hidden (ncx:hidden extension used in the YANG definition), then no help will be available for the parameter, even though it is accessible.  This also apples to the help command.  Any command or parameter designated as ncx:hidden will be treated as an unknown identifier, and no help will be given.

Note: Skipping mandatory nodes with the '?s' command is affected by the --bad-data configuration parameter and $$bad-data system variable.  An error, warning, or confirmation check may occur.  Refer to the CLI Reference for more details.

Note: If there are any YANG defined values (e.g., enumeration, bits, default-stmt) available for the current parameter, then pressing the tab key will list the full or partial completions available.

2.2.5 Using XPath Expressions

There are some command parameters, such as the --target parameter for the create command, that accept XPath absolute path expressions.

If prefixes are present, then they must match the set of XML prefixes in use at the time.  Use the show modules command to see the current set of prefixes.

If prefixes are not used, then the first available matching XML namespace will be used instead.

If the starting forward slash character ('/') is missing, then it will be added.

# these are all the same value

yangcli:fill> system

yangcli:fill> /system

yangcli:fill> /sys:system

It is important to remember 2 simple rules to avoid common errors in XPath expressions:

1. String constants must be quoted with single quote characters.
   The expression [name=fred] is not the same as [foo='fred'].
   The former compares the 'name' node value to the 'fred' node value.
   The latter compares the 'name' node value to the string 'fred'.

2. The double quote character ('”') is not allowed in XPath --select parameter expressions because the expression will be sent to the server inside a double-quoted string.

If an incomplete XPath absolute path expression is entered, and the script interpreter is in interactive mode, then the user will be prompted to fill in any missing mandatory nodes or key leafs.

# complete form of ifMtu leaf

yangcli:fill> /interfaces/interface[name='eth0']/ifMtu

# incomplete form of ifMtu leaf

yangcli:fill> /interfaces/interface/ifMtu

Filling key leaf <name>:

Enter string value:

The --select parameter for the xget and xget-config commands accepts full XPath expressions.  The expression must yield a node-set result in order to be used as a filter in NETCONF get and get-config operations.

One of the simplest XPath filters to use is the descendant-or-self filter ('//<expr>').

For example, this command will retrieve all instances of the 'ifMtu' leaf:

xget //ifMtu

When interface (or any list) entries are returned by netconfd, they will contain the the entire path back to the root of the YANG module, not just the specified node.  Also, any key leafs within a list are added.  This is only done if the XPath expression is missing any predicates for key leafs.

This is different than XPath 1.0 as used in XSLT.  Since NETCONF get and get-config operations return complete XML instance documents, not node-sets, the ancestor nodes and naming nodes need to be added.

# reply shown with --display-mode=plain

data {

  interfaces {

             interface eth0 {

   name eth0

   ifMtu 1500

     }

             interface eth1 {

   name eth1

   ifMtu 1518

     }

  }

}

2.2.6 Special Parameter Handling

Some special handling of YANG data structures is done by the script interpreter.

Containers

Some parameters, such as the --source and --target parameters in many commands, are actually represented as a container with a single child -- a choice of several leaf nodes.  In this situation, just the name of the desired leaf node can be entered (when in idle mode), as the 'contents' of the container parameter.

sget-config /system source=candidate

Choices and Cases

If a parameter name exact-match is not found, and a partial match is attempted, then choice and case node names will be ignored, and not cause a match.

Since these nodes never appear in the XML PDUs they are treated as transparent nodes (wrt/ parameter searches) unless they are specified with their full name.

Parameters that are a choice of several nodes, similar to above, except without a parent container node, (e.g., --help-mode) can be omitted.  The accessible child nodes within the case nodes can be entered directly (e.g., sget --target parameter).

# this is not allowed because 'help-mode' is not complete

yangcli> help --command=help --help-mo=brief

# this is allowed because 'help-mode' is complete,

# even though help-mode is a choice and 'brief' is

# an empty leaf

yangcli> help help help-mode=brief

# choice and case names are transparent when

# searching for parameter names, so the

# following command is the same as above

yangcli> help help brief

Lists and Leaf-Lists

When filling a data structure and a descendant node is entered, which is a YANG list or leaf-list, then multiple entries can be entered.  After the node is filled in, there will be a prompt (Y/N, default no) to add more list or leaf-list entries.

Binary Data Type

The YANG binary data type is supported.  Parameters of this type should be entered in plain text and they will be converted to binary format.

2.2.7 Command Completion

The 'tab' key is used for context-sensitive command completion:

• If no command has been started, a list of available commands is printed

• If a partial command is entered, a list of commands which match the characters entered so far is printed

• If a command is entered, but no parameters, then a list of available parameters is printed

• If a command is entered, and the cursor is within a command name, then a list of parameters which match the characters entered so far is printed

• If a command is entered, and the cursor is after a command name, but not within a value string, then a list of available parameters is printed

• If a command is entered, and the cursor is within a command value, then a list of possible values which match the characters entered so far is printed.  Note that not all data types support value completion at this time.

• If no values are available, but a default value is known, that value will be printed

Command list example: no NETCONF session is active:

yangcli> <hit tab key>

cd       fill     history  mgrload  quit     run      

connect  help     list     pwd      recall   show     

Command list example: NETCONF session is active

yangcli andy@myserver.example.com> <hit tab key>

cd                   get-schema           recall

close-session        help                 replace

commit               history              restart

connect              insert               run

copy-config          kill-session         save

create               list                 sget

create-subscription  load                 sget-config

delete               load-config          show

delete-config        lock                 shutdown

discard-changes      merge                unlock

edit-config          mgrload              validate

fill                 no-op                xget

get                  pwd                  xget-config

get-config           quit

2.2.8 Command Line Editing

The command line parser is based on libtecla, a freely available library.

The home page is located here:

http://www.astro.caltech.edu/~mcs/tecla/

The complete user guide for configuring libtecla is located here:

http://www.astro.caltech.edu/~mcs/tecla/tecla.html

If the file $HOME/.teclarc exists, then libtecla will use it to configure the key bindings.

By default, libtecla uses emacs key bindings.  There is no need for any further libtecla configuration if emacs mode is desired.

In order to use the vi editor key bindings, the $HOME/.teclarc file must exist, and it must contain the following line:

edit-mode vi

Custom key bindings are also available.  Refer to the libtecla documentation for more details on command line editing key customization.

The control key sequence (^F == control key and f key at the same time). The letter is not case-sensitive, so ^F and ^f are the same command.

The alt key sequence (M-f == alt key and f key at the same time). The letter is not case-sensitive, so M-F and M-f are the same command.

The following table shows the the most common default key bindings:

Common editing key bindings

2.2.9 Command History

Each command line is saved in the command history buffer, unless a password is being entered in parameter mode.

By default, the previous history line (if any) will be shown if the ^P key is pressed.

By default, the next history line (if any) will be shown if the ^N key is pressed.

In addition, the history command can be used to control the command line buffer further.  This command has 4 sub-modes:

• show: show maximum of N history entries (default is 25)

• clear: clear the history buffer

• save: save the history buffer to a file

• load: load the history buffer from a file

By default, the command line history buffer is loaded when the program starts, and saved when the program exits.  This behavior can be turned off by setting the --autohistory configuration parameter to 'false'.

Refer to the Command Reference section for more details on the history command.

2.2.10 Command Responses

The command output and debugging messages within yangcli is controlled by the current log level (error, warn, info, debug, debug2, debug3).

If a command is executed by the script interpreter, then a response will be printed, depending on the log level value.

If the log level is 'info' or higher, and there were no errors and no response, then the string 'OK' is printed.

yangcli> $foo = 7

  OK

yangcli>

If the log-level is set to 'error' or 'warn', then the 'OK' messages will be suppressed.

If the log level is set to 'debug' or higher, then responses from the server will be echoed to the log (file or STDOUT).  The current display mode will be used when printing data structures such as <rpc-error> and <notification> element contents.

If an error response is received from the server, it will always be printed to the log.

yangcli andy@myserver> create /system

Filling container /system:

RPC Error Reply 5 for session 8:

rpc-reply {

   rpc-error {

      error-type application

      error-tag access-denied

      error-severity error

      error-app-tag limit-reached

      error-path /nc:rpc/nc:edit-config/nc:config/sys:system

      error-message 'max-access exceeded'

   }

}

yangcli andy@myserver>

Refer the the --log-level parameter in the CLI Reference for more details.

2.3 NETCONF Sessions

The yangcli program can be connected to one NETCONF server at a time.

Run multiple instances of yangcli to control multiple agents at once.

Use the connect command to start a NETCONF session.

This section explains how to use yangcli to manage a NETCONF server, once a session is established.

When a NETCONF session starts up, a <capability> exchange is done, and the server reports exactly what content it supports.  This information is used extensively to customize the session, and report errors and warnings for the session.

2.3.1 Connection Startup Screen

If the --log-level is set to 'info' of higher, then a startup screen will be displayed when a NETCONF session is started. It contains:

• startup banner

• client session ID

• server session ID

• protocol capabilities supported by the server

  • Includes revision-date of supported module

• YANG modules supported by the server

  • Includes any features and deviations supported in the module

• Enterprise specific capabilities supported by the server

• Default target database (<candidate> or <running>)

• Save operation mapping for the server

• with-defaults reporting capability reported by the server

The following example shows a typical startup screen connecting to the netconfd server:

NETCONF session established for andy on myserver

Client Session Id: 1

Server Session Id: 8

Server Protocol Capabilities

   Protocol Version: RFC 4741

   candidate:1.0

   rollback-on-error:1.0

   validate:1.0

   xpath:1.0

   notification:1.0

   interleave:1.0

   with-defaults:1.0

   netconf-monitoring:1.0

   schema-retrieval:1.0

Server Module Capabilities

   ietf-inet-types@2009-11-10

   ietf-netconf-monitoring@2009-11-20

   ietf-with-defaults@2009-07-01

      Features:

         with-defaults

   ietf-yang-types@2009-11-10

   nc-notifications@2008-07-14

   notifications@2008-07-14

   test@2009-12-26

      Features:

         feature1

         feature3

         feature4

   yuma-app-common@2010-01-25

   yuma-interfaces@2009-11-21

   yuma-mysession@2009-08-11

   yuma-nacm@2009-11-21

   yuma-ncx@2009-12-21

   yuma-proc@2009-11-21

   yuma-system@2009-12-27

   yuma-types@2010-01-25

Server Enterprise Capabilities

   None

Default target set to: <candidate>

Save operation mapped to: commit

Default with-defaults behavior: explicit

Additional with-defaults behavior: trim:report-all

Checking server Modules...

yangcli andy@myserver>

2.3.2 Server Tailored Context

While a NETCONF session is active, the set of available YANG modules will be set to the modules that the server is using, if the --autoload configuration parameter is enabled.

If the :schema-retrieval capability is also available on the server, then the <get-schema> operation will be attempted for any YANG module specified in the <hello> message capabilities, but not available to the yangcli program.

When the server module capabilities are analyzed by the yangcli client, the entire YANG module search path is checked for the specific module advertised in the capability.  All the modules are partially parsed to check the actual namespace and revision date values.  The following fields must exactly match in order for yangcli to use a local YANG module, if --autoload=true.

• module name

• module revision date (if any)

• module namespace

If the namespace URI value is different, it indicates that there is either a bug in one of the conflicting YANG modules, or that two different naming authorities picked the same module name.   In this case, a warning will be generated during session initialization.

Any data returned from the server for YANG modules not currently available will be treated as a YANG 'anyxml' node, instead of the (unknown) YANG data type.

If the module contains YANG features that are not advertised in the <capabilities> exchange, then those data definitions will not be available (by default) for use in yangcli commands.

If the module contains an object with a 'when' statement, and the 'when' XPath expression evaluates to 'false', then that data definition will not be available (by default) for use in yangcli commands.

The help command will be tailored to the modules, capabilities, features, and module deviations reported by the server in <capability> exchange.

2.3.3 Retrieving Data

There are 6 commands available to retrieve generic data (i.e., an arbitrary subset of an entire NETCONF database):

All the high-level retrieval operations support the $$with-defaults system variable.  The <with-defaults> parameter will be added the the NETCONF PDU if this variable is set to a value other than 'none' (the default).  This system variable will be used as the default if not entered directly.

sget /system --with-defaults=$$with-defaults

This parameter can also be specified directly, each time the command is used.

xget-config //ifMtu --with-defaults=trim

The $$bad-data system variable is used to control how invalid operations and data are sent to the server.  The xget and xget-config commands are affected by this parameter.  If the :xpath capability was not advertised by the server when the session started, an error or warning may occur if these commands are used.

If any data is received that yangcli does not understand, then a warning message will be printed and the data will be treated as if it was defined with the YANG 'anyxml' data type.

2.3.4 Modifying Data

The following commands are available to modify generic data (i.e., an arbitrary subset of an entire NETCONF database):

All the high-level editing operations use the --target parameter reported by the server when the session started up.  If the server did not report the :candidate or  :writable-running capabilities, then there will be no writable target, and an error will occur if these commands are entered.

All the high-level editing operations support the $$default-operation system variable.  The <default-operation> parameter will be added the the NETCONF <edit-config> PDU if this variable is set to a value other than 'not-used'.  The default is the enumeration 'none', which means do not use any default operation, and only use the explicit nc:operation attribute.

All the high-level editing operations support the $$test-option system variable.  The <test-option> parameter will be added the the NETCONF <edit-config> PDU if this variable is set to a value other than 'none' (the default).  This system variable will be used as the default if not entered directly.

replace /interfaces/interface[name='eth0']/ifMtu \

--test-option=$$test-option \

--value=$newvalue

This parameter can also be specified directly, each time the command is used.

$newvalue = 1518

replace /interfaces/interface[name='eth0']/ifMtu \

--test-option=test-only \

--value=$newvalue

All the high-level retrieval operations support the $$error-option system variable.  The <error-option> parameter will be added the the NETCONF <edit-config> PDU if this variable is set to a value other than 'none' (the default).  This system variable will be used as the default if not entered directly.

replace /interfaces/interface[name='eth0']/ifMtu \\

--error-option=$$error-option \

--value=1518

This parameter can also be specified directly, each time the command is used.

replace /interfaces/interface[name='eth0']/ifMtu \

--error-option=rollback-on-error \

--value=1518

The high level save command is mapped to other commands, depending on the capabilities reported by the server.

save command

2.3.5 Using Notifications

The create-subscription command is used to start receiving notifications.

The netconfd server will include a <sequence-id> element in any notification that is saved in the replay buffer.  This unsigned integer can be used to help debug notification filters (i.e., if non-consecutive <sequence-id> values are received, then the notification was filtered, or dropped due to access control policy).

If any replay notifications are desired, then the --startTime parameter must be included.  At the end of the stored notifications, the server will send the <replayComplete> event.  This notification type is not saved, and will not be found in the server replay buffer, if replay is supported by the server.  The netconfd server will not include a <sequence-id> element in this notification type.

If the notification subscription should stop at a certain time, then the --stopTime parameter must be included.  At the end of the stored notifications, the server will send the <replayComplete> event, followed by the <notificationComplete> event.  .  This notification type is not saved, and will not be found in the server replay buffer, if replay is supported by the server.  The netconfd server will not include a <sequence-id> element in this notification type.

Notifications are printed to the log, using the current $$display-mode system variable setting, when and if they are received.

Notifications are also logged.  Use the eventlog command to access the notifications stored in the event log.

2.3.6 Configuration Parameters That Affect Sessions

The --server, --user, and --password configuration parameters can be used to start a NETCONF session automatically at startup time.  The connect command will only be attempted at startup time if the --server parameter is present.

If all 3 of these parameters are present at startup time, then no interactive prompting for additional optional parameters will be done.  Instead the connect command will be invoked right away.

During normal operation, the --optional configuration parameter, or the
$$optional system variable, can be used to control interactive prompting for optional parameters.

The --server parameter is saved in the $$server system variable, which can be overwritten at any time.  If set, this will be used as the initial default value for the --server parameter in the connect command.

The --fixorder configuration parameter can be used to control XML PDU ordering.  If set to 'true', then the PDU will be reordered (if needed),to use the canonical order, according to the YANG specification.  If 'false', the order parameters are entered at the command line will be their NETCONF PDU order as well.  The default is 'true'.  To send the server incorrectly ordered data structures on purposes, set this parameter to 'false'.

The --user parameter is saved in the $$user system variable, which can be overwritten at any time.  If set, this will be used as the initial default value for the --user parameter in the connect command.

The --with-defaults configuration parameter, or the $$with-defaults system variable, can be used to set the default value for the 'with-defaults' parameter extension for the NETCONF get, get-config, and copy-config protocol operations.  The default is 'none'.

The --error-option configuration parameter, or the $$error-option system parameter, can be used to set the default value for the --error-option parameter for the NETCONF edit-config protocol operation.  The default is 'none'.

The --test-option configuration parameter, or the $$test-option system parameter, can be used to set the default value for the --test-option parameter for the NETCONF edit-config protocol operation.  The default is 'none'.

The --bad-data configuration parameter, or the $$bad-data system variable, can be used to control how yangcli handles parameter values that are known to be invalid, or usage of optional protocol operations that the current session does not support.  The default value is 'check'.  To use yangcli in a testing mode to send the server incorrect data on purpose, set this parameter to 'warn' or 'ignore'.

2.3.7 Trouble-shooting NETCONF Session Problems

If the NETCONF session does not start for any reason, one or more error messages will be printed, and the prompt will indicate 'idle' mode.  This section assumes that the server is netconfd, and these debugging steps may not apply to all NETCONF agents.

If the NETCONF session does not start:

• make sure the server is reachable

  • try to 'ping' the server and see if it responds

• make sure the SSH server is responding

  • try to login in to the server using normal SSH login on port 22

• make sure a firewall is not blocking TCP port 830

  • try to connect to the NETCONF server using the --port=22 option

• make sure the netconf-subsystem is configured correctly in /etc/ssh/sshd_config
  there should be the proper configuration commands for NETCONF to work.  For example, the netconfd server configuration might look like this:

•  

Port 22

Port 830

Subsystem netconf /usr/sbin/netconf-subsystem

•  

• make sure the netconfd server is running. Use the unix 'ps' command, or check the netconfd log file, to make sure it is running.

   

ps -alx | grep netconf

(look for 1 'netconfd and N 'netconf-subsystem' -- 1 for

each active session)

•  

• make sure the user name is correct

  • This must be a valid user name on the system

• make sure the password is correct

  • This must be the valid password (in /etc/passwd or /etc/shadow) for the specified user name

If the NETCONF session stops responding:

• make sure the server is still reachable

  • try to 'ping' the server and see if it responds

• make sure the SSH server is still responding

  • try to login in to the server using normal SSH login on port 22

If the NETCONF server is not accepting a certain command:

• make sure the command (or parameters used in the command) is actually supported by the server.

  • There may be features, when statements, or deviation statements that indicate the server does not support the command or one or more of its parameters.

• make sure that access control configured on the server is not blocking the command.  The error-tag should be 'access-denied' in this case.

If the NETCONF server is not returning the expected data in a <get> or <get-config> protocol operation::

• Make sure all the parameters are supported by the server

  • the :xpath capability must be advertised by the server to use the 'select' attribute in the <get> or <get-config> operations

  • the :with-defaults capability must be advertised by the server to use the <with-defaults> parameter

• if using a filter, try to retrieve the data without a filter and see if it is there

• make sure that access control configured on the server is not blocking the retrieval. There will not be any error reported in this case.  The server will simply skip over any unauthorized data, and leave it out of the <rpc-reply>.

• set the logging level to debug2 or higher, and look closely at the PDUs being sent to the server.  Set the display mode to a value other than 'plain' to make sure the correct namespaces are being used in the request.

If an <edit-config> operation is failing unexpectedly:

• make sure that access control configured on the server is not blocking the request. The error-tag should be 'access-denied' in this case.

• make sure an unsupported parameter or parameter value is not used

  • <test-option> is not supported unless the :validate capability is advertised by the server

  • <error-option> = 'rollback-on-error' is not supported unless the
    :rollback-on-error capability is advertised by the server

• if the request contains an edit to a nested data structure, make sure the parent data structure(s) are in place as expected.  The <default-operation> parameter is set to 'none' in the high level editing operations, so any data 'above' the edited data must already exist.

• set the logging level to debug2 or higher, and look closely at the PDUs being sent to the server.  Set the display mode to a value other than 'plain' to make sure the correct namespaces are being used in the request.

2.4 Command Reference

This section describes all the yangcli local and remote commands built-in when using the netconfd server.

There may be more or less commands available, depending on the YANG modules actually loaded at the time.

The specific NETCONF capabilities needed are listed for each remote command.  No capabilities are ever needed for a local command.

It is possible that other agents will support protocol operations that netconfd does not support.  If yangcli has the YANG file available for the module, then it can be managed with the high level commands.  Low-level commands can still be used with external data (e.g., @mydatafile.xml).

Any YANG rpc statement can be used as a remote yangcli command.  Refer to the server vendor documentation for details on the protocol operations, database contents, and notification definitions that they support.

2.4.1 cd

The cd command is used to change the current working directory.

cd command

Command Parameters:

• dir

  • type: string

  • usage: mandatory

  • default: none

  • The 'dir' string must contain a valid directory specification

Positive Response:

• the new current working directory is printed

Negative Response:

• an error message will be printed describing the error

Usage:

yangcli> cd ~/modules

Current working directory is /home/andy/modules

yangcli> cd --dir=$YUMA_HOME

Current working directory is /home/andy/swdev/yuma/trunk/netconf

yangcli>

2.4.2 close-session

The close-session command is used to terminate the current NETCONF session.  A NETCONF server should always accept this command if it is valid, and not reject it due to access control enforcement or if the server is in notification delivery mode.

close-session command

Command Parameters:

• none

Positive Response:

• the session is terminated and the command prompt is changed to indicate idle mode

Negative Response:

• an <rpc-error> message will be printed describing the error

Usage:

yangcli andy@myserver> close-session

RPC OK Reply 2 for session 10:

yangcli>

Reference:

• RFC 4741, section 7.8

2.4.3 commit

The commit command is used to save the edits in the <candidate> database into the <running> database.  If there are no edits it will have no effect.

commit command

Command Parameters:

• confirmed

  • type: empty

  • usage: optional

  • default: none

  • capabilities needed: :confirmed-commit

  • This parameter requests a confirmed commit procedure.  The server will expect another commit command before the confirm-timeout time period expires.

• confirm-timeout

  • type: uint32 (range: 1 .. max)

  • usage: optional

  • default: 600 seconds

• • capabilities needed: :confirmed-commit

• • This is the number of seconds to request before the timeout.
    The 'confirmed' leaf must also be present for this parameter to have any affect.

Positive Response:

• the session is terminated and the command prompt is changed to indicate idle mode

Negative Response:

• an <rpc-error> message will be printed describing the error

Usage:

yangcli andy@myserver> commit

RPC OK Reply 5 for session 10:

yangcli andy@myserver>

Reference:

• RFC 4741, section 8.3.4

2.4.4 connect

The connect command is used to start a session with a NETCONF server.

If there already is a NETCONF session active, then an error message will be printed and the command will not be executed.

connect command

Command Parameters:

• server

  • type: inet:ip-address (string containing IP address or DNS name

  • usage: mandatory

  • default: previous server used, if any, will be presented as the default, but not used automatically

  • This parameter specifies the server address for the session.

• password

  • type: string (ncx:password)

  • usage: mandatory

  • default: previous password used, if any, will be presented as the default, but not used automatically

  • This parameter specifies the password string to use to establish the session.  It will not be echoed in parameter mode or saved in the command history buffer.

• port

  • type: uint16

  • usage: optional

  • default: 830

  • This parameter specifies the TCP port number that should be used for the session.

• timeout

  • type: uint32 (0 = no timeout, otherwise the number of seconds to wait)

  • usage: optional

  • default: set to the $$timeout system variable, default 30 seconds

  • This parameter specifies the number of seconds to wait for a response from the server before giving up.  The session will not be dropped if a remote command times out, but any late response will be dropped.  A value of zero means no timeout should be used, and yangcli will wait forever for a response.

• user

  • type: string

  • usage: mandatory

  • default: previous user name used, if any, will be presented as the default, but not used automatically

  • This parameter specifies the user name to use for the session.  This must be a valid user name on the NETCONF server.

Positive Response:

• the session is started and the prompt changes to include  the 'user@server' string.

Negative Response:

• One or more error messages will be printed.  Refer to the section on trouble-shooting NETCONF Session problems for more details.

Usage:

yangcli> connect myserver user=andy password=yangrocks

<startup screen printed>

yangcli andy@myserver>

2.4.5 copy-config

The copy-config command is used to copy one entire NETCONF database to another location.

Not all possible parameter combinations will be supported by every server.  In fact, the NETCONF protocol does not require any parameters to be supported unless the :startup or :url capabilities is supported by the server.

If the server supports the :startup capability, then it must support:

yangcli andy@myserver> copy-config source=running target=startup

This is the standard way to save a snapshot of the current running configuration in non-volatile storage, if the server has a separate startup database.  If not, the server will automatically save any changes to the running configuration to non-volatile storage.

copy-config command

Command Parameters:

• source

  • type: container with 1 of N choice of leafs

  • usage: mandatory

  • default: none

  • This parameter specifies the name of the source database for the copy operation.

  • container contents: 1 of N:

    • candidate

      • type: empty

      • capabilities needed: :candidate

    • running

      • type: empty

      • capabilities needed: none

    • startup

      • type: empty

      • capabilities needed: startup

    • config:

      • type: container (in-line configuration data)

      • capabilities needed: none

    • url

      • type: yang:uri

      • capabilities needed: :url, and the scheme used in the URL must be specified in the :url capability 'schemes' parameter

      • To enter this parameter, the interactive mode must be used.  The shorthand mode (source=url) cannot be used, since this parameter contains a string.

• target

  • type: container with 1 of N choice of leafs

  • usage: mandatory

  • default: none

  • This parameter specifies the name of the target database for the copy operation.

  • container contents: 1 of N:

    • candidate

      • type: empty

      • capabilities needed: :candidate

    • running

      • type: empty

      • capabilities needed: :writable-running (still optional to implement)

        • netconfd does not support this mode

    • startup

      • type: empty

      • capabilities needed: startup

    • url

      • type: yang:uri

      • capabilities needed: :url, and the scheme used in the URL must be specified in the :url capability 'schemes' parameter.

      • To enter this parameter, the interactive mode must be used.  The shorthand mode (target=url) cannot be used, since this parameter contains a string.

• with-defaults

  • type: enumeration (none report-all trim explicit)

  • usage: optional

  • default: none

  • capabilities needed: with-defaults

  • This parameter controls how nodes containing only default values are copied to the target database.

Positive Response:

• the server returns <ok/>

Negative Response:

• An error message will be printed if errors are detected locally.

• An <rpc-error> message will be printed if the server detected an error.

Usage:

yangcli andy@myserver> copy-config source=candidate

Enter a number of the selected case statement:

 1: case candidate:

      leaf candidate

 2: case running:

      leaf running

 3: case startup:

      leaf startup

 4: case url:

      leaf url

Enter choice number [1 - 4]:

yangcli andy@myserver:copy-config> 4

Filling optional case /copy-config/input/target/config-source/url

Enter string value for leaf <url>:

yangcli andy@myserver:copy-config> file://configs/myconfig.xml

RPC OK Reply 12 for session 10:

yangcli andy@myserver>

Reference:

• RFC 4741, section 7.3

2.4.6 create

The create command is a high-level <edit-config> operation.  It is used to create some new  nodes in the default target database.

A target node is specified (in 1 of 2 ways), and then the data structure is filled in.  Only mandatory nodes will be filled in unless the $$optional system variable is set to 'true'.

Refer to the fill command for more details on interactive mode data structure completion.

create command

Command Parameters:

• choice 'from' (not entered)

  • type: choice of case 'varref' or case 'from-cli'

  • usage: mandatory

  • default: none

  • This parameter specifies the where yangcli should get the data from, for the create operation.  It is either a user variable or from interactive input at the command line.

    • varref

      • type: string

      • usage: mandatory

      • default: none

      • This parameter specifies the name of the user variable to use for the target of the create operation.  The parameter must exist (e.g., created with the fill command) or an error message will be printed.

    • case from-cli (not entered)

      • target

        • type: string

        • usage: mandatory

        • default: none

        • This parameter specifies the database target node of the create operation. This is an ncx:schema-instance string, so any instance identifier, or absolute path expression, or something in between, is accepted.

      • optional

        • type: empty

        • usage: optional

        • default: controlled by $$optional system variable

        • This parameter controls whether optional nodes within the target will be filled in.  It can be used to override the $$optional system variable, when it is set to 'false'.

      • value

        • type: anyxml

        • usage: mandatory

        • default: none

        • This parameter specifies the value that should be used for the contents of the target parameter.  If it is entered, then the interactive mode prompting for missing parameters will be skipped, if this parameter is complete (or all mandatory nodes present if the $$optional system variable is 'false').  For example, if the target is a leaf, then specifying this parameter will always cause the interactive prompt mode to be skipped.

• timeout

  • type: uint32 (0 = no timeout, otherwise the number of seconds to wait)

• • usage: optional

  • default: set to the $$timeout system variable, default 30 seconds

  • This parameter specifies the number of seconds to wait for a response from the server before giving up.  The session will not be dropped if a remote command times out, but any late response will be dropped.  A value of zero means no timeout should be used, and yangcli will wait forever for a response.

System Variables:

• $$default-operation

  • The <default-operation> parameter for the <edit-config> operation will be derived from this variable.

• $$error-option

  • The <error-option> parameter for the <edit-config> operation will be derived from this variable

• $$test-option

  • The <test-option> parameter for the <edit-config> operation will be derived from this variable

Positive Response:

• the server returns <ok/>

Negative Response:

• An error message will be printed if errors are detected locally.

• An <rpc-error> message will be printed if the server detected an error.

Usage:

yangcli andy@myserver> create varref=myvar

RPC OK Reply 10 for session 10:

yangcli andy@myserver > create /nacm/rules/data-rule \

(user will be prompted to fill in the data-rule contents)

RPC OK Reply 11 for session 10:

yangcli andy@myserver > create \

target=/nacm/rules/data-rule[name='test rule']/comment \

value=”this test rule is temporary. Do not remove!”

(no user prompting; <edit-config> request sent right away)

RPC OK Reply 12 for session 10:

yangcli andy@myserver>

Reference:

• RFC 4741, section 7.2

2.4.7 create-subscription

The create-subscription command is used to start receiving notifications from the server.

The :notification capability must be supported by the server to use this command.

Unless the :interleave capability is also supported by the server, then only the close-session command can be used while notifications are being delivered.

create-subscription command

Command Parameters:

• stream

  • type: string

  • usage: optional

  • default: 'NETCONF'

  • This parameter specifies the name of the notification stream for this subscription request.  Only the 'NETCONF' stream is mandatory to implement. Any other stream contains vendor-specific content, and may not be fully supported, depending on the stream encoding.

• filter

  • type: anyxml (same as the <get> or <get-config> filter parameter)

  • usage: optional

  • default: none

  • This parameter specifies a boolean filter that should be applied to the stream.  This is the same format as the standard <filter> element in RFC 4741, except that instead of creating a subset of the database for an <rpc-reply> PDU, the filter is used as a boolean test to send or drop each notification delivered from the server.

    • If any nodes are left in the 'test response', the server will send the entire notification.

    • If the result is empty after the filter is applied to the “test response”, then the server will not send the notification at all.

    • It is possible that access control will either cause the a notification to be dropped entirely, or may be pruned and still delivered.  The standard is not clear on this topic.  The netconfd server will prune any unauthorized payload from an eventType, but if the <eventType> itself is unauthorized, the entire notification will be dropped.

• startTime

  • type: yang:date-and-time

  • usage: optional

  • default: none

  • This parameter causes any matching replay notifications to be delivered by the server, if notification replay is supported by the server.  A notification will match if its <eventTime> value is greater or equal to the value of this parameter.

  • After all the replay notifications are delivered, the server will send a <replayComplete> eventType, indicating there are no more replay notifications that match the subscription request.

• stopTime

  • type: yang:date-and-time

  • usage: optional (not allowed unless startTime is also present)

  • default: none

  • This parameter causes any matching replay notifications to be delivered by the server, if notification replay is supported by the server.  A notification will match if its <eventTime> value is less than the value of this parameter.  

    • This parameter must be greater than the startTime parameter, or an error will be returned by the server.

    • If this parameter is used, then the entire subscription will stop after this specified time, even if it is in the future.  The <notificationComplete> eventType will be sent by the server when this event occurs.

    • If this parameter is not used (but startTime is used), then the server will continue to deliver 'live' notifications after the <replayComplete> eventType is sent by the server.

Positive Response:

• the server returns <ok/>

Negative Response:

• An error message will be printed if errors are detected locally.

• An <rpc-error> message will be printed if the server detected an error.

Usage:

yangcli andy@myserver> create-subscription

RPC OK Reply 13 for session 10:

yangcli andy@myserver > create-subscription \

startTime=2009-01-01T00:00:00Z

RPC OK Reply 14 for session 10:

yangcli andy@myserver >

Reference:

• RFC 5277, section 2.1.1

2.4.8 delete

The delete command is a high-level <edit-config> operation.  It is used to delete an existing subtree in the default target database.

A target node is specified, and then any missing key leafs (if any) within the data structure are filled in.  If the target is a leaf-list, then the user will be prompted for the value of the leaf-list node to be deleted.

Refer to the fill command for more details on interactive mode data structure completion.

delete command

Command Parameters:

• target

  • type: string

  • usage: mandatory

  • default: none

  • This parameter specifies the database target node of the delete operation. This is an ncx:schema-instance string, so any instance identifier, or absolute path expression, or something in between, is accepted.

System Variables:

• $$default-operation

  • The <default-operation> parameter for the <edit-config> operation will be derived from this variable.

• $$error-option

  • The <error-option> parameter for the <edit-config> operation will be derived from this variable

• $$optional

  • Controls whether optional descendant nodes will be filled into the target parameter contents

• $$test-option

  • The <test-option> parameter for the <edit-config> operation will be derived from this variable

Positive Response:

• the server returns <ok/>

Negative Response:

• An error message will be printed if errors are detected locally.

• An <rpc-error> message will be printed if the server detected an error.

Usage:

yangcli andy@myserver > delete /nacm/rules/data-rule \

(user will be prompted to fill in the data-rule 'name' key leaf)

RPC OK Reply 15 for session 10:

yangcli andy@myserver > delete \

target=/nacm/rules/data-rule[name='test rule']/comment

(no user prompting; <edit-config> request sent right away)

RPC OK Reply 16 for session 10:

yangcli

Reference:

• RFC 4741, section 7.2

2.4.9 delete-config

The delete-config command is used to delete an entire NETCONF database.

Not all possible target parameter values will be supported by every server.  In fact, the NETCONF protocol does not require that any database be supported by this operation.

If the server supports the :url capability, then it may support deletion of local file databases in this manner.:

delete-config command

Command Parameters:

• target

  • type: container with 1 of N choice of leafs

  • usage: mandatory

  • default: none

  • This parameter specifies the name of the target database for the delete operation.

  • container contents: 1 of N:

    • startup

      • type: empty

      • capabilities needed: startup

      • a server may support this target

    • url

      • type: yang:uri

      • capabilities needed: :url, and the scheme used in the URL must be specified in the :url capability 'schemes' parameter.

      • To enter this parameter, the interactive mode must be used.  The shorthand mode (target=url) cannot be used, since this parameter contains a string.

      • a server may support this parameter

Positive Response:

• the server returns <ok/>

Negative Response:

• An error message will be printed if errors are detected locally.

• An <rpc-error> message will be printed if the server detected an error.

Usage:

yangcli andy@myserver> delete-config target=startup

RPC OK Reply 17 for session 10:

yangcli andy@myserver >

Reference:

• RFC 4741, section 7.4

2.4.10 discard-changes

The discard-changes command is used to delete any edits that exist in the <candidate> database, on the NETCONF server.  The server will only accept this command if the :candidate capability is supported.  If the <candidate> database is locked by another session, then this request will fail with an 'in-use' error.

discard-changes command

Command Parameters: none

Positive Response:

• the server returns <ok/>

Negative Response:

• An error message will be printed if errors are detected locally.

• An <rpc-error> message will be printed if the server detected an error.

Usage:

yangcli andy@myserver> discard-changes

RPC OK Reply 18 for session 10:

yangcli andy@myserver >

Reference:

• RFC 4741, section 8.3.4.2

2.4.11 edit-config

The edit-config command allows a subset of a NETCONF database on the server to be changed.

If the server supports the :url capability, then it may support editing of local file databases.

If the server supports the :candidate capability, then it will allow edits to the <candidate> database.

If the server supports the :writable-running capability, it will support edits to the <running> database.

It is not likely that a server will support the <candidate> and <running> database as targets at the same time, since changes to the <running> configuration would not be reflected in the <candidate> database, while it was being edited by a different session.

edit-config command

Command Parameters:

• default-operation

  • type: enumeration (merge replace none)

  • usage: optional

  • default: merge

  • This parameter specifies which edit operation will be in effect at the start of the operation, before any nc:operation attribute is found.

    • The high-level edit operations provided by yangcli will set this parameter to 'none'.  This is the safest value, since only subtrees that have an explicit nc:operation attribute in effect can possibly be altered by the command.

    • If the value is 'merge', then any missing nodes in the database will be automatically created as needed.

    • If the value is 'replace', then the target database will be pruned to match the edits, as needed.  Only the data from the config parameter will remain if this value  is used.  (Use with extreme caution).

• error-option

  • type: enumeration (stop-on-error continue-on-error rollback-on-error

  • usage: optional

  • default: stop-on-error

  • This parameter specifies what the server should do when an error is encountered.

    • The rollback-on-error value is only allowed if the :rollback-on-error capability is supported by the server.

    • The standard is not clear what continue-on-error really means.  It is suggested that this value not be used.  It is possible that the server will validate all input parameters before making any changes, no matter how this parameter is set.

• choice edit-content (not entered)

  • config

    • type: anyxml

    • usage: mandatory

    • default: none

    • This parameter specifies the subset of the database that should be changed.  This is the most common way to edit a NETCONF server database, since it is mandatory to support by all agents.

  • url

    • type: yang:uri

    • capabilities needed: :url, and the scheme used in the URL must be specified in the :url capability 'schemes' parameter.

    • To enter this parameter, the interactive mode must be used.  The shorthand mode (target=url) cannot be used, since this parameter contains a string.

• target

  • type: container with 1 of N choice of leafs

  • usage: mandatory

  • default: none

  • This parameter specifies the name of the target database for the edit operation.

  • container contents: choice: 1 of N:

    • candidate

      • type: empty

      • capabilities needed: :candidate

    • running

      • type: empty

      • capabilities needed: :writable-running

• test-option

  • type: enumeration (test-then-set set test-only)

  • usage: optional

  • default: set (unless :validate capability is supported, the 'test-then-set' is the default value)

  • This parameter specifies how the server should test the edit-content parameter before using it.

    • If the value is 'set' (normal case), the server will apply validation tests as needed for the individual data structures being edited

    • The value 'test-then-set' is only allowed if the :validate capability is supported by the server.  The server will test if the entire database will be valid after the edits are made, before making any changes to the candidate configuration.

      • This mode is very resource intensive.  Set this parameter to 'set' for better performance, and run the validation tests manually with the validate command.

    • The value 'test-only' is not supported by all agents.   It will be in the next version of the NETCONF protocol, but is non-standard at this time.

      • Use this value to check if a specific edit should succeed or not, allowing errors to be corrected before altering the database for real.

Positive Response:

• the server returns <ok/>

Negative Response:

• An error message will be printed if errors are detected locally.

• An <rpc-error> message will be printed if the server detected an error.

Usage:

yangcli andy@myserver> edit-config target=candidate \

default-operation=merge \

test-option=test \

error-option=stop-on-error \

config=@myconfig.xml

RPC OK Reply 19 for session 10:

yangcli andy@myserver >

Reference:

• RFC 4741, section 7.2

2.4.12 elif

The elif command is used to define a conditional command block after an if command.

This command must be entered within the same script as the if command, when used within a script.  It can be used zero or more times within an if command sequence.

The expr parameter is used to specify the XPath expression to test if the elif conditional block is true or false.  A false block will be skipped and a true block will be executed.  The command prompt will contain the string '[F]' while inside a false conditional block in interactive mode.  This expression string should be entered with quotes to avoid misinterpreting any whitespace or special characters.

The docroot parameter (if present) specifies the XML document that the 'expr' parameter should be evaluated against.  This is optional, since only XPath path expressions need to refer to a document.

Even if the 'expr' expression is true, the conditional block will only be executed if no conditional block in the if command sequence has already been executed.

if command

....

[elif command]

....

[elif-command]

...

[else command]

...

end command

elif command

Command Parameters:

• expr

  • type: XPath expression string

  • usage: mandatory

  • default: none

  • This parameter specifies the XPath expression to determine if the following commands are within a true or false conditional block.

• docroot

  • type: anyxml

  • usage: optional (typically a variable reference is used)

  • default: none

  • This parameter specifies the XML document that should be used if the expr XPath expression references any path nodes.

Positive Response:

• the server returns <ok/>

Negative Response:

• An error message will be printed if errors are detected locally.

  • elif without a previous if command will cause an error

  • elif following an 'else' command will cause an error

  • invalid XPath expression or invalid docroot reference will cause an error

Usage:

yangcli andy@myserver> elif expr='$x > 4'

yangcli andy@myserver >

2.4.13 else

The else command is used to define a final conditional command block after an if command.

This command must be entered within the same script as the if command, when used within a script.  It can be used zero or one time within an if command sequence.

The conditional command block following the else command will only be executed if no conditional block has already been executed in the same if command sequence.

if command

....

[elif command]

....

[elif-command]

...

[else command]

...

end command

else command

Command Parameters: none

Positive Response:

• the server returns <ok/>

Negative Response:

• An error message will be printed if errors are detected locally.

  • else without a previous if command will cause an error

Usage:

yangcli andy@myserver> else

yangcli andy@myserver >

2.4.14 end

The end command is used to terminate a conditional command block after an if command block, or after a 'while' command.

This command must be entered within the same script as the if or while command, when used within a script.

if command

....

[elif command]

....

[elif-command]

...

[else command]

...

end command

while command

....

end command

end command

Command Parameters: none

Positive Response:

• the server returns <ok/>

Negative Response:

• An error message will be printed if errors are detected locally.

  • else without a previous if command will cause an error

Usage:

yangcli andy@myserver> end

yangcli andy@myserver >

2.4.15 eval

The eval command is used to evaluate an XPath expression..

The expr parameter is used to specify the XPath expression to evaluate.   This expression string should be entered with quotes to avoid misinterpreting any whitespace or special characters.

The docroot parameter (if present) specifies the XML document that the 'expr' parameter should be evaluated against.  This is optional, since only XPath path expressions need to refer to a document.

eval command

Command Parameters:

• expr

  • type: XPath expression string

  • usage: mandatory

  • default: none

  • This parameter specifies the XPath expression to determine if the following commands are within a true or false conditional block.

• docroot

  • type: anyxml

  • usage: optional (typically a variable reference is used)

  • default: none

  • This parameter specifies the XML document that should be used if the expr XPath expression references any path nodes.

Positive Response:

• the server returns <ok/>

Negative Response:

• An error message will be printed if errors are detected locally.

  • elif without a previous if command will cause an error

  • elif following an 'else' command will cause an error

  • invalid XPath expression or invalid docroot reference will cause an error

Output:

• data

  • type: anyxml

  • This element will contain the result from the XPath expression.  A node-set result will produce a complex element return value, and all other XPath result types will produce a string return value.

Usage:

yangcli andy@myserver> $x = eval '$x + 1'

yangcli andy@myserver > $sysname = eval '//sysName' docroot=$backup

2.4.16 eventlog

The eventlog command is used to view or clear all or part of the notification event log.  This log will be empty if no well-formed notifications have been received from any server.

The eventlog show command is used to display some event log entries.

The eventlog clear command is used to delete some event log entries.

If no parameters are entered, it is the same as entering 'eventlog show=-1'.

The event log is not automatically emptied when a session terminates, in case the session was dropped unexpectedly.  New entries will be appended to the event log as new sessions and/or subscriptions are started.

eventlog command

Command Parameters:

• choice eventlog-action (not entered):

  • type: choice of case 'show-case' or leaf 'clear'

  • usage: optional

  • default: show=-1 is used as the default if nothing entered

  • This parameter specifies the event log action that should be performed.

    • clear

      • type: int32 (-1 to clear all entries; 1 to max to delete N entries)

      • usage: optional

      • default: -1

      • This parameter specifies the maximum number of event log entries to be deleted, starting from the oldest entries in the event log.  The value -1 means delete all the entries.  Otherwise the value must be greater than zero, and up to that many entries will be deleted.

    • case show-case (not entered)

      • choice help-mode (not entered) (default choice is 'normal')

        • brief

          • type: empty

          • usage: optional

          • default: none

          • This parameter specifies that brief documentation mode should be used.  The event log index, sequence ID, and <eventType> will be displayed in this mode.

        • normal

          • type: empty

          • usage: optional

          • default: none

          • This parameter specifies that normal documentation mode should be used.  The event log index, <eventTime>, sequence ID, and <eventType> will be displayed in this mode.

        • full

          • type: empty

          • usage: optional

          • default: none

          • This parameter specifies that full documentation mode should be used.  The event log index, <eventTime>, sequence ID, and <eventType> will be displayed in this mode.  In addition, the entire contents of the notification PDU will be displayed, using the current $$display-mode setting.

      • show

        • type: int32 (-1 for all, 1 to max for N entries)

        • usage: optional

        • default: -1

        • This parameter specifies the number of event log entries that should be displayed. The value '-1' indicates all the entries should be displayed. Otherwise, the value must be greater than zero, indicating the number of entries to display.

      • start

        • type: uint32

        • usage: optional

        • default: 0

        • This parameter specifies the start position in the event log to start displaying entries.  The first entry is number zero.  Each time the event log is cleared, the numbering restarts.

System Variables:

• $$display-mode

  • The log entries printed when help-mode='full' are formatted according to the current value of this system variable.

Positive Response:

• the event log entries are printed or cleared as requested

Negative Response:

• An error message will be printed if errors are detected.

Usage:

yangcli andy@myserver> eventlog show=5 start=3

[3] [2009-07-10T02:21:10Z] (4) <sysSessionStart>

[4] [2009-07-10T02:23:14Z] (5) <sysSessionEnd>

[5] [2009-07-10T02:23:23Z] (6) <sysSessionStart>

[6] [2009-07-10T02:24:52Z] (7) <sysConfigChange>

[7] [2009-07-10T02:24:57Z] (8) <sysSessionEnd>

yangcli andy@myserver>

2.4.17 fill

The fill command is used to create a user variable for reuse in other commands.

It is used in an assignment statement to create a variable from various sources.

If it is not used in an assignment statement, then the result will not be saved, so the command will have no effect in this case.

The value contents will mirror the subtree within the NETCONF database indicated by the target parameter.  If not completely provided, then missing descendant nodes will be filled in interactively, by prompting for each missing node.

fill command

Command Parameters:

• optional

  • type: empty

  • usage: optional

  • default: controlled by $$optional system variable

  • This parameter controls whether optional nodes within the target will be filled in.  It can be used to override the $$optional system variable, when it is set to 'false'.

• target

  • type: string

  • usage: mandatory

  • default: none

  • This parameter specifies the database target node of the create operation. This is an ncx:schema-instance string, so any instance identifier, or absolute path expression, or something in between, is accepted.

• value

  • type: anyxml

  • usage: mandatory

  • default: none

  • This parameter specifies the content to use for the filled variable.

    • If this parameter is not entered, then the user will be prompted interactively to fill in the target data structure.

    • If a string is entered, then the target value being filled must be a leaf or leaf-list.

    • If a variable reference is entered, then it will be used as the content, if the target value being filled is a leaf or a leaf-list.

    • If the target value is a complex object, then the referenced variable must also be a complex object of the same type.

    • An error will be reported if the global or local variable does not reference the same object type as the target parameter.

System Variables:

• $$optional

  • Controls whether optional descendant nodes will be filled into the target parameter contents

Positive Response:

• OK

Negative Response:

• An error message will be printed if errors are detected.

Output:

• data

  • type: anyxml

  • The data structure will mirror the requested target object.

  • The variable (if any) will retain the target object name and namespace so it can be used in other operations more easily.  In the example below, the $my_interface local variable will have the module name 'interfaces' and name 'interface', when used in other commands such as create or merge.

Usage:

yangcli> $my-interface = fill \

target=/interfaces/interface optional

(user will be prompted to fill in all fields

of the <interface> element)

  OK

yangcli>

2.4.18 get

The get command is used to retrieve data from the server.

get command