Yuma yangcli Manual

YANG-Based Unified Modular Automation Tools

NETCONF Over SSH Client

Version 2.2

Last Updated:  January 26, 2012

Table Of Contents

Yuma yangcli Manual

1 Preface        5

1.1 Legal Statements        5

1.2 Additional Resources        5

1.2.1 WEB Sites        5

1.2.2 Mailing Lists        6

1.3 Conventions Used in this Document        6

2 yangcli User Guide        7

2.1 Introduction        8

2.1.1 Features        8

2.1.2 Starting yangcli        9

2.1.3 Stopping yangcli        11

2.1.4 Statements        11

2.1.5 Commands        12

2.1.6 Variables        14

2.1.7 Files        17

2.1.8 Scripts        17

2.1.9 Configuration Parameter List        19

2.2 Invoking Commands        21

2.2.1 Command Prompt        22

2.2.2 Command Name        25

2.2.3 ncx:default-parm Extension        25

2.2.4 Parameter Mode Escape Commands        27

2.2.5 Using XPath Expressions        27

2.2.6 Special Parameter Handling        28

2.2.7 Command Completion        30

2.2.8 Command Line Editing        31

2.2.9 Command History        32

2.2.10 Command Responses        32

2.3 NETCONF Sessions        33

2.3.1 Connection Startup Screen        33

2.3.2 Server Tailored Context        35

2.3.3 Retrieving Data        37

2.3.4 Modifying Data        37

2.3.5 Using Notifications        39

2.3.6 Configuration Parameters That Affect Sessions        39

2.3.7 Trouble-shooting NETCONF Session Problems        40

2.4 Command Reference        42

2.4.1 alias        42

2.4.2 aliases        44

2.4.3 cd        45

2.4.4 close-session        46

2.4.5 commit        47

2.4.6 connect        48

2.4.7 copy-config        50

2.4.8 create        53

2.4.9 create-subscription        55

2.4.10 delete        57

2.4.11 delete-config        59

2.4.12 discard-changes        60

2.4.13 edit-config        61

2.4.14 elif        64

2.4.15 else        65

2.4.16 end        66

2.4.17 eval        67

2.4.18 eventlog        69

2.4.19 fill        71

2.4.20 get        73

2.4.21 get-config        74

2.4.22 get-locks        76

2.4.23 get-my-session        78

2.4.24 get-schema        79

2.4.25 help        81

2.4.26 history        84

2.4.27 if        87

2.4.28 insert        88

2.4.29 kill-session        91

2.4.30 list        92

2.4.31 load        95

2.4.32 lock        97

2.4.33 log-debug        98

2.4.34 log-error        99

2.4.35 log-info        100

2.4.36 log-warn        101

2.4.37 merge        102

2.4.38 mgrload        104

2.4.39 no-op        105

2.4.40 pwd        106

2.4.41 quit        107

2.4.42 recall        107

2.4.43 release-locks        108

2.4.44 replace        109

2.4.45 restart        111

2.4.46 run        112

2.4.47 save        113

2.4.48 set-log-level        114

2.4.49 set-my-session        115

2.4.50 sget        116

2.4.51 sget-config        119

2.4.52 show        122

2.4.53 shutdown        127

2.4.54 start-timer        127

2.4.55 stop-timer        128

2.4.56 unlock        129

2.4.57 unset        131

2.4.58 uservars        132

2.4.59 validate        133

2.4.60 while        134

2.4.61 xget        136

2.4.62 xget-config        138

3 CLI Reference        142

3.1 --aliases-file        142

3.2 --alt-names        142

3.3 --autoaliases        142

3.4 --autocomp        143

3.5 --autohistory        143

3.6 --autoload        144

3.7 --autouservars        144

3.8 --bad-data        144

3.9 --batch-mode        145

3.10 --config        145

3.11 --datapath        146

3.12 --default-module        146

3.13 --deviation        147

3.14 --display-mode        147

3.15 --feature-disable        148

3.16 --feature-enable        149

3.17 --feature-enable-default        149

3.18 --fixorder        150

3.19 --force-target        150

3.20 --help        151

3.21 --help-mode        151

3.22 --indent        152

3.23 --log        152

3.24 --log-append        153

3.25 --log-level        153

3.26 --match-names        154

3.27 --modpath        155

3.28 --module        156

3.29 --ncport        156

3.30 --password        157

3.31 --private-key        157

3.32 --protocols        157

3.33 --public-key        158

3.34 --runpath        158

3.35 --run-command        159

3.36 --run-script        159

3.37 --server        159

3.38 --subdirs        160

3.39 --time-rpcs        160

3.40 --timeout        161

3.41 --transport        161

3.42 --use-xmlheader        161

3.43 --user        162

3.44 --uservars-file        162

3.45 --version        163

3.46 --warn-idlen        163

3.47 --warn-linelen        164

3.48 --warn-off        164

3.49 --yuma-home        165

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 User Manual

        Yuma  netconfd  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

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

• •User configurable command aliases that can be saved and restored. 

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. 1.Read-only system variables 

2. 2.Read-write system variables 

3. 3.Read-write global user variables (saved in $HOME/.yuma directory) 

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

The uservars command can be used to load or store these variables so they are loaded at boot-time.  By default, the XML file used to store these variables is $HOME/.yuma/yangcli_uservars.xml.

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

• •If a session is active, and whitespace followed by the forward slash '/' character is entered, a list of top-level data node names is printed.  Once a top-level name and a trailing slash '/'  character is entered, pressing the tab key again will print the names of the child nodes of the current data node.  Only schema-node strings are supported at this time.  Auto-completion will not work if predicates are present in the absolute path expression. 

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

The '!' character is special when editing commands.  If the first character is '!',  and it is followed by a number or a non-zero character, the line will be interpreted as a recall request:

• •yangcli> !42    == recall command number 42 (same as recall 42) 

• •yangcli> !get   == recall the most recent command line starting with 'get' 

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