../_images/logo.png

  • YANG-Based Unified Modular Automation Tools

  • NETCONF Over SSH Client

  • NETCONF Over TLS Client

  • RESTCONF Over HTTP(S) Client

  • NETCONF Over SSH Call Home Server

  • NETCONF Over TLS Call Home Server

Program Components

../_images/yangcli-pro_featured_img_081417.png

yangcli-pro Introduction

The yangcli-pro program is a NETCONF over SSH client application. It is driven directly by YANG modules, and provides a simple but powerful application interface that can utilize any YANG file to drive the user interface. Full server management features and server testing features are supported. There is no configuration required at all to use any YANG file, since the yangdump-pro YANG compiler is built into the application.

yangcli-pro Features

The yangcli-pro client has the following features:

  • Support for multiple sessions to multiple servers at once

  • Support for configured named sessions saved in a secure configuration file

  • Easy to use configuration mode for editing; provides an IOS CLI-like user interface to edit server configurations

    • Command line history, recall

    • Output filtering with 'pipe' commands

    • Terminal pagination with –More-- prompt controls

  • Supports NETCONF 1.0, NETCONF 1.1, and RESTCONF protocols

  • Automated session reconnect for NETCONF and RESTCONF sessions

  • Automated shadow configuration monitoring for each session; can be referenced in scripts and tab completion

  • Automated notification monitoring for each session; callback framework for event handling

  • Automated regression testing support to verify server operation, including

    • setup and cleanup sections per test-suite

    • multiple tests per suite

    • each test step can check for ok, rpc-error, data responses

  • Automatic recording of test suites

    • The record-test command used to automatically record commands in a re-usable test script.

    • The test-suite command is used to run previously recorded tests and verify the same results are obtained as when the test was recorded.

  • Automatic monitoring of server notifications

    • The <create-subscription> operation is automatically sent if --autonotif=true and the server supports notifications.

    • Configuration change events are monitored to know when configuration updates are needed for that session

  • Automatic shadowing of the running configuration

    • The <get-config> operation is automatically sent if --autoconfig=true. A shadow of the running configuration is maintained for the session, and updated automatically if notifications are active.

    • The config command uses the shadow configuration for tab completion and comparison purposes.

  • Automatic support for all NETCONF protocol operations, including several 'short-hand' commands for the most common operations:

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

  • Differentiate between local and server commands when the <tab> and ?<cr> used. A star '*' will be printed after each server command.

  • Configurable NETCONF Call-Home over SSH support (RFC 8071)

  • Support the privileged mode in yp-shell for config mode.

  • Support of restricting all editing to the yp-shell config mode.

  • Configurable break-key behavior to cancel current command ot exit program

  • Ability to invoke yangcli or shell scripts to automate command processing

  • Supports the Event Condition Action (ECA) to allow the user to run shell scripts based on a notification.

Starting yangcli-pro

Warning

yangcli-pro and yp-shell do not support running multiple instances of the program at once on the same host

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

The yangcli-pro program can be invoked several ways:

  • To get the current version and exit:

    yangcli-pro --version
    
  • To get program help and exit:

    yangcli-pro --help
    
    yangcli-pro --help --brief
    
    yangcli-pro --help --full
    
  • To start an interactive session with the default parameters:

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

    yangcli-pro --log=mylogfile
    
  • To start an interactive session and append to an existing log file:

    yangcli-pro --log=mylogfile --log-append
    
  • To get parameters from a configuration file:

    yangcli-pro --config=~/yangcli-pro.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-pro 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 (e.g., --port or --timeout) may be entered as well. All parameters can be entered from a config file, and/or the command line.

    yangcli-pro --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-pro --run-script=mytestscript --server=myserver.example.com --user=andy --password=yangrocks
    
  • 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-pro --run-script=mytestscript --batch-mode --server=myserver.example.com --user=andy --password=yangrocks
    
  • 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-pro --run-command=”sget /system”  --batch-mode --server=myserver.example.com --user=andy --password=yangrocks
    
  • To automatically connect to a server, and just listen for notifications, and never exit, use the --autonotif=true** parameter instead of the --run-command or --run-script parameter. The --batch-mode parameter must be provided in this mode.

    yangcli-pro --batch-mode --autonotif=true --server=myserver.example.com --user=andy --password=yangrocks
    

Stopping yangcli-pro

To terminate the yangcli-pro program, use the quit command.

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

Statements

The yangcli-pro script interpreter accepts several types of statements:

yangcli-pro Statements

type

description

example

command

invoke a local command and/or send an <rpc> to the server

sget /system

variable assignment

set a user variable to some value

$system = sget /system

file assignment

set the contents of a file to some value

@save.txt = $system

variable deletion

delete a user variable or clear a system variable

$system =

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:

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

Commands

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

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

There are 3 types of yangcli-pro commands:

  • local: the command is executed within the yangcli-pro 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-pro does not recognize as a local command is treated as a remote command available on the server.

  • config mode: the command is executed within the yangcli-pro application, in config mode. This is only available while a session is established.

Local Commands

Command

Description

alias

Show or set a specific yangcli-pro command alias

aliases

Manage the yangcli-pro command aliases

auto-test

Run automatic edit testing on the specified session

cache

Clear 1 or all entries from the YANG module cache

cd

Change the current working directory

clear

Clear the screen

config

Enter the configuration mode for the current session

connect

Connect to a server and start a NETCONF session

device-cfg

Access a named device configuration

devices-cfg

Access the named device configuration file

elif

Start an 'else-if' conditional block

else

Start an 'else' conditional block

enable-password

Enable the privileged mode in yp-shell to enter the config mode.

end

End an 'if' or 'while' block

eval

Evaluate an XPath expression

event-handler-cfg

Access an event handler mapping configuration.

event-handlers-cfg

Controls access to the saved event-handlers file.

eventlog

View or clear the notification event log

exit

Exit configuration mode for the current session

fill

Fill a user variable

group

Manage the session groups.

help

Get context-sensitive help

history

Manage the command history buffer

if

Start an 'if' conditional block

list

List modules, objects, or other properties of the session

log-debug

Log a debug message

log-error

Log an error message

log-info

Log an info message

log-warn

Log a warning message

mgrload

Load a YANG file into the client only

nvsave

Save the running datastore to the startup datastore

pwd

Print the current working directory

quit

Exit the program

recall

Recall a line from the command history buffer

record-test

Record commands and responses for a regression test

refresh-library

Refresh the module version list used to determine the 'best-match' for imports.

run

Run a script

run-shell

Run a shell script. The allow-shell parameter must be ‘true’

schema-server-cfg

Access a named schema-server-cfg configuration

schema-servers-cfg

Access the named schema-servers-cfg configuration file

session

Set the current session

session-cfg

Access a named session configuration

sessions-cfg

Access the named session configuration file

show

Show variables and objects currently available

sleep

Sleep for a number of seconds (for use in scripts)

start-rpc-timing

Start <rpc> timing mode and save statistics to a file

stop-session

Stop a named session

stop-timer

Stop a script timer and display the elapsed time

terminal

Set the terminal length

test-suite

Access a configured unit-test suite for automated testing

user-cfg

Access a named user configuration

users-cfg

Access the named user configuration file

update-config

Update the shadow configuration for the current session<

unset

Remove a command alias from memory

uservars

Manage the yangcli-pro user variables

while

Start a 'while' conditional loop block

Standard NETCONF Commands

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

Command

Description

cancel-commit

Cancel the current confirmed commit procedure

cancel-subscription

Stop receiving NETCONF notifications (RFC 5277 subscription)

close-session

Close the current NETCONF session

commit

Make the candidate database be the running config

copy-config

Copy an entire NETCONF database

create-subscription

Start receiving NETCONF notifications (RFC 5277 subscription)

delete-config

Delete an entire NETCONF database

delete-subscription

Terminate a NETCONF notification subscription for the current session

discard-changes

Discard any edits in the candidate database

edit-config

Alteration of the target database

establish-subscription

Start receiving NETCONF notifications (RFC 8639 subscription)

get

Filtered retrieval of state data and running config

get-config

Filtered retrieval of any NETCONF database

get-data

Filtered retrieval of a NETCONF NMDA database

get-schema

Get a data model definition file from the server

kill-session

Force close another NETCONF session

kill-subscription

Force close a notification subscription for another NETCONF session

lock

Lock a NETCONF database that is currently unlocked

modify-subscription

Modify the NETCONF notification subscription parameters

resync-subscription

Re-synchronize a YANG Push datastore subscription

unlock

Unlock a NETCONF database that is currently locked

validate

Validate the contents of a NETCONF database

Custom NETCONF Commands

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

Command

Description

action

Invoke a YANG 1.1 <action>

create

Invoke an <edit-config> create operation

delete

Invoke an <edit-config> delete operation

delete-all

Invoke an <edit-config> delete operation using the netconfd-pro "delete-all" nc:operation value.

get-locks

Lock all the databases with the <lock> operation

get-walk

Walk the entries of a YANG list.

insert

Invoke an <edit-config> YANG insert operation

merge

Invoke an <edit-config> merge operation

rawrpc

Invoke an <rpc> operation using raw XML

release-locks

Unlock all the locked databases with the <unlock> operation

remove

Invoke an <edit-config> remove operation

remove-all

Invoke an <edit-config> remove operation using the netconfd-pro "remove-all" nc:operation value.

replace

Invoke an <edit-config> replace operation

save

Save the current edits on the server in NV-storage

sget

Invoke a <get> operation with a subtree filter

sget-config

Invoke a <get-config> operation with a subtree filter

sget-data

Invoke a <get-data> operation with a subtree filter

xget

Invoke a <get> operation with an XPath filter

xget-config

Invoke a <get-config> operation with an XPath filter

xget-data

Invoke a <get-data> operation with an XPath filter

Extended netconfd-pro Commands

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

Command

Description

get-my-session

Retrieve session customization parameters

load

Load a module into the server.

no-op

No operation.

restart

Restart the server.

set-log-level

Set the server logging verbosity level.

set-my-session

Set session customization parameters.

shutdown

Shutdown the server.

Variables

The yangcli-pro 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 (saved in $HOME/.yuma directory)

  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

Syntax

Description

Example

$$<variable-name>

Left hand side: set the global variable to some value

$$saved_get = get

$$<variable-name>

Right hand side: access the value of a global variable

fill --target=$$mytarget

$<variable-name>

Left hand side: set the local variable to some value

$myloglevel = $$log-level

$<variable-name>

Right hand side: access the value of any variable with this name

$myuser = $user

Read-only System Variables

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

Variable

Description

$$HOME

$HOME environment variable

$$HOSTNAME

$HOST or $HOSTNAME environment variable

$$LANG

$LANG environment variable

$$PWD

$PWD environment variable, when yangcli-pro was invoked

$$SHELL

$SHELL environment variable

$$USER

$USER environment variable

$$YUMAPRO_DATAPATH

$YUMAPRO_DATAPATH environment variable

$$YUMAPRO_HOME

$YUMAPRO_HOME environment variable

$$YUMAPRO_MODPATH

$YUMAPRO_MODPATH environment variable

$$YUMAPRO_RUNPATH

$YUMAPRO_RUNPATH environment variable

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

Variable

Description

$$aliases-file

--aliases-file configuration parameter

$$allow-shell

--allow-shell configuration parameter

$$alt-names

--alt-names configuration parameter

$$ask-password

--ask-password configuration parameter

$$auto-discard-changes

--auto-discard-changes parameter

$$auto-keepalive

--auto-keepalive configuration parameter

$$auto-reconnect

--auto-reconnect configuration parameter

$$auto-reconnect-interval

--auto-reconnect-interval configuration parameter

$$auto-reconnect-max

--auto-reconnect-max configuration parameter

$$autoaliases

--autoaliases configuration parameter

$$autocomp

--autocomp configuration parameter

$$autoconfig

--autoconfig configuration parameter

$$autoconfig-conf-mode

--autoconfig-conf-mode configuration parameter

$$autodevices

--autodevices configuration parameter

$$autoeventhandlers

--autoeventhandlers configuration parameter

$$autohistory

--autohistory configuration parameter

$$autoload

--autoload configuration parameter

$$autoload-cache

--autoload-cache configuration parameter

$$autoload-get

--autoload-get configuration parameter

$$autoload-save-cache

--autoload-save-cache configuration parameter

$$autonotif

--autonotif configuration parameter

$$autonvsave

--autonvsave configuration parameter

$$autoschemaservers

--autoschemaservers configuration parameter

$$autosessions

--autosessions configuration parameter

$$autotest

--autotest configuration parameter

$$autousers

--autousers configuration parameter

$$autouservars

--autouservars configuration parameter

$$bad-data

--bad-data configuration parameter

$$break-key-mode

--break-key-mode configuration parameter

$$callhome-address

--callhome-address configuration parameter

$$callhome-enabled

--callhome-enabled configuration parameter

$$callhome-port

--callhome-port configuration parameter

$$callhome-tls-port

--callhome-tls-port configuration parameter

$$check-output

--check-output configuration parameter

$$check-output-error

--check-output-error configuration parameter

$$check-replies

--check-replies configuration parameter

$$check-replies-error

--check-replies-error configuration parameter

$$config-autosave

--config-autosave configuration parameter

$$config-commit-mode

--config-commit-mode configuration parameter

$$config-edit-mode

--config-edit-mode configuration parameter

$$default-module

--default-module configuration parameter

$$default-operation

<default-operation> parameter for <edit-config> operations

$$display-mode

--display-mode configuration parameter

$$echo-notif-loglevel

--echo-notif-loglevel configuration parameter

$$echo-notifs

--echo-notifs configuration parameter

$$echo-replies

--echo-replies configuration parameter

$$encoding

--encoding configuration parameter

$$error-option

<error-option> parameter for <edit-config> operations

$$fill-optional

--fill-optional configuration parameter

$$fixorder

--fixorder configuration parameter

$$help-width

--help-width configuration parameter

$$ignore-missing-vars

--ignore-missing-vars configuration parameter

$$indent

--indent configuration parameter

$$keepalive-interval

--keepalive-interval configuration parameter

$$leaflist-multi-line

--leaflist-multi-line configuration parameter

$$log-level

--log-level configuration parameter

$$match-names

--match-names configuration parameter

$$message-indent

--message-indent configuration parameter

$$optional

--optional configuration parameter

$$prompt

--prompt configuration parameter (yp-shell only)

$$prompt-type

--prompt-type configuration parameter

$$save-session-vars

--save-session-vars configuration parameter

$$script-input

--script-input configuration parameter

$$server

--server configuration parameter

$$shell-command

--shell-command configuration parameter

$$ssl-fallback-ok

--ssl-fallback-ok configuration parameter

$$term-length

--term-length configuration parameter

$$test-option

<test-option> parameter for the <edit-config> operation

$$test-suite-file

--test-suite-file configuration parameter

$$time-rpcs

--time-rpcs configuration parameter

$$time-rpcs-stats

--time-rpcs-stats configuration parameter

$$time-rpcs-stats-file

--time-rpcs-stats-file configuration parameter

$$timeout

--timeout configuration parameter

$$use-data-templates

--use-data-templates configuration parameter

$$use-rawxml

--use-rawxml configuration parameter

$$use-session-vars

--use-session-vars configuration parameter

$$use-traceid

--use-traceid configuration parameter

$$use-xmlheader

--use-xmlheader configuration parameter

$$user

--user configuration parameter

$$uservars-file

--uservars-file configuration parameter

$$with-defaults

<with-defaults> retrieval parameter

$$with-term-msg

--with-term-msg configuration parameter

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/.yumapro/yangcli-pro_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.

Read-write Session User Variables

If the $$use-sessionvars variable is true, then global variables will be treated as session-specific variables, while the active session is a named session. In this case, if a unrecognized global variable (e.g., $$foo) is used in the left-hand side of an assignment statement, then a session user variable will be created with that name. If the session user variable already exists, then its value will be overwritten.

If data templates are used, then the session-specific variables will be used to replace a variable reference within the template, instead of the global variable.

Files

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

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

session1> @foo.yang = get-schema --identifier=foo --format=YANG

session1> mgrload --module=foo
  • If the file extension is “.yang”, “.log”, “.txt”, or “.text”, then the value (or command output) will be saved, and yangcli-pro will strip off the outermost XML (if needed) to save the requested file as a pure text file.

  • If the file extension is ".json", the file will be saved in JSON format.

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

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

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

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

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

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 executed, 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).

The following script does not do any useful work. It is provided to demonstrate some simple script constructs.

# Sample Script 1

$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

The following script demonstrates how to run multiple edits on the ietf-interfaces.yang data module:

# Sample Script 2

$x = 0
$y = interfaces
$z = interface
$value = ianaift:l2vlan

while '$x < 5'
    create /if:$y/if:$z[if:name='vlan$x']/if:type value=$value
    commit
    $x = eval '$x + 1'
end

Configuration Mode Editing

Configuration mode (often called "config mode") can be used if the current session is connected to a server. If not, requests to enter configuration mode will be rejected with an error message.

This additional editing mode is similar to a router command line interface. It can be used to edit YANG datastore nodes with a simplified interface:

  • A small number of Configuration Mode Commands are available

  • All YANG configuration data node names are command keywords

  • Data node names can be abbreviated just like RPC operation parameter names

  • Tab completion for data node names is context-sensitive and based on the YANG modules available within the session

  • The current context node can be changed to different YANG data nodes within the configuration, which are called Sub-Modes

  • The command sequence follows the YANG data node hierarchy

    XPath Example:
    
       /interfaces/interface[name='eth0']
    
    CLI Example:
    
       interfaces interface eth0
    
    CLI Example With Allowed Keyword Matching:
    
       int int eth0
    
  • List entries are always followed by all the key leaf values (e.g., interface eth0).

    • The names of the key leafs are omitted (e.g. 'name' is not specified after 'interface')

    • Quotes are needed for key values if they have any whitespace or special characters

Configuration Mode Variations

There are some CLI parameters that affect how config mode works. Each parameter may also have a corresponding system variable that can be set at run-time instead of program invocation time.

  • --autocomp: If set to 'false' then only exact node names are allowed. The default is 'true' which allows partial matching of keywords.

  • --autoconfig: If set to 'false' then tab completion may not be available. A copy of the 'running' datastore is maintained if 'true'. This is needed to populate existing nodes and values.

  • --autoconfig-conf-mode: If 'autoconfig is set to 'false' then and this parameter is also set to 'false' then some tab completion will not be available.

  • --with-enable-mode: Only available in 'yp-shell'. If 'true' then enable mode must be entered first before config mode can be entered.

  • --restrict-edit-mode: Only available in 'yp-shell'. If 'true' then config mode is the only editing mode available to users.

  • --config-autosave: Controls how edits are saved to NV-storage on the server.

  • --config-commit-mode: If 'true' then edits will be applied to the 'candidate' datastore. This allows edits to be sent in any order to the server, and then applied all at once, using the commit command.

  • --config-edit-mode: This most important parameter controls how edits are applied to the server. The apply and exit commands work differently, depending on this parameter.

    There are 3 modes:

    • line: The edit(s) are automatically applied after each line is entered.

    • level: The edits(s) are automatically applied with the exit command, or manually applied with the apply command. This is the default mode.

    • manual: The edit(s) are only applied manually with the apply command.

    Refer to the config-edit-mode Examples section for more details.

Configuration Mode Commands

The following table shows the special configuration mode commands and keywords. They are only allowed in configuration mode. The behavior may depend on the config mode variation that is in use.

Command

Description

apply

Apply any pending edits to the

config-commit

Use commit operation to apply any pending edits

do

Invoke a normal command in configuration mode

exit

Return to the parent mode and apply any pending edits

gotop

Exit all sub-modes until the top level config mode is reached

no

Keyword to start a command to delete a data node

return

Return to normal mode from configuration mode without applying any edits

Changing Config Modes and Sub-Modes

Enter Configuration Mode

To enter configuration mode, use the config command:

mysession> config term

mysession#

Once configuration mode is active, the prompt will change (notice (c) above), the available top-level configuration data nodes advertised by the server are available as 'commands'. Only a few special commands are available in configuration mode:

  • apply: Use this command to force all pending edits to be applied to the current session

  • exit: Use this command to exit the current configuration sub-mode to its parent mode. If already at the top level, then this command will cause configuration mode to be terminated

Enter Configuration Sub-Mode

The configuration context node can be changed to simplify editing. Conceptually, the context node represents a YANG container or list node within the server database.

mysession# interfaces

mysession(interfaces)# int eth0

mysession(interface)#

Exit Configuration Sub-Mode

The exit command is used to exit the current configuration level and return to the parent level.

If the config-edit-mode parameter is set to 'level' then any pending edits at the current level will be applied to the server.

mysession(interface)# exit
mysession(interfaces)#

Go to the Top in Configuration Mode

The gotop command is used to exit the current configuration level and return to the top-level.

  • This is similar to the exit command, except the prompt returns to the top-level instead of the parent level.

  • Using this command at the top-level instead of a sub-mode has no affect.

  • This is much different than the return command which discards all pending edits and exits configuration mode

  • If the config-edit-mode parameter is set to 'level' then any pending edits at the current level will be applied to the server.

  • This command is available starting in the 22.10T-4 release

mysession(interface)# gotop

mysession#

Return from Configuration Editing Mode

The return command is used to exit all configuration levels and leave configuration mode.

Any pending edits will be abandoned and not applied to the current session.

mysession(interface)# return

mysession>

Editing Server Database Parameters

  • Specifying the name of an existing container or list node will cause new edits to be merged into the existing entry

  • Specifying the name of a node that does not currently exist will cause it to be created

  • Using the 'no' keyword before any node names will cause a node to be deleted (if it exists)

Creating or Modifying Server Database Parameters

mysession(interface)# mtu 9000

mysession(interface)# exit

Applying 1 edit to session [mysession]

mysession(interfaces)# exit

mysession# exit

mysession>

Since the configuration editing mode is set to 'level' (the default). the 'mtu' edit is not applied until the exit or gotop or apply command is given. All pending edits are applied to the current session with these commands.

Commands can be entered in a flexible manner. The same command as above could be entered in 1 command line:

mysession# int int eth0 mtu 9000

Applying 1 edit to session [mysession]

mysession#

Deleting Server Database Parameters

To delete a database node, or return it to its default value, the 'no' prefix is used:

mysession# no int int eth0 mtu

Applying 1 edit to session [mysession]

mysession#

Note that to delete leaf nodes no value is given. A value is only required for YANG list and leaf-list data nodes, to identity the keys for the instance that should be deleted.

Escaping Configuration Mode With 'do' Command

In order to enter normal yangcli-pro commands while in configuration mode, the 'do' keyword is used. Only a limited set of commands can be accessed from configuration mode in this manner.

mysession# do show session

[session info shown]

mysession#

yangcli-pro Configuration Parameter List

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

Parameter

Description

--aliases-file

Specifies the command aliases file to use.

--allow-shell

Enable or disable the run-shell command.

--alt-names

Controls whether alternate names will be checked for UrlPath searches.

--ask-password

Controls whether the 'connect' command will prompt for password parameter (if it is not provided).

--auto-discard-changes

Controls automatic sending of <discard-changes> to cleanup edit

--auto-keepalive

Controls automatic sending of keepalive messages. NOT IMPLEMENTED - IGNORED.

--auto-reconnect

Controls automatic reconnecting to dropped sessions

--auto-reconnect-interval

Controls how often automatic reconnect is attempted.

--auto-reconnect-max

Controls maximum number of reconnect attempts

--autoaliases

Controls automatic loading and saving of the command aliases

--autocomp

Controls whether partial commands are allowed or not.

--autoconfig

Controls whether the running configuration will be retrieved automatically for active sessions.

--autoconfig-conf-mode

Controls whether the running configuration will be retrieved automatically for active sessions, while editing in config mode

--autodevices

Controls whether saved device configurations are loaded at startup and saved upon exit.

--autoeventhandlers

Controls whether the saved event_handlers will be loaded into memory at startup and saved to file at exit.

--autohistory

Controls whether th command line history buffer will be automatically loaded at startup and saved on exit.

--autoload

Controls whether modules used by the server will be loaded automatically, as needed.

--autoload-cache

Controls whether the modules retrieved with the <get-schema> operation are cached for use by the running instance of yangcli-pro.

--autoload-get

Controls whether the <get> operation will be used to retrieve the /netconf-state/schemas sub-tree.

--autoload-save-cache

Controls whether the cached YANG modules will be saved upon exit

--autonotif

Controls whether notifications will automatically be enabled when a session starts.

--autonvsave

Controls whether the 'save' and 'apply' commands will NV-save the configuration changes or not.

--autosessions

Controls whether saved session configurations are loaded at startup and saved upon exit.

--autoschemaservers

Controls whether the saved schema servers will be loaded into memory at startup and saved to file at exit.

--autosessions

Controls whether the saved sessions will be loaded into memory at startup and saved to file at exit.

--autotest

Controls whether the saved test suites will be loaded into memory at startup and saved to file at exit.

--autousers

Controls whether saved user configurations are loaded at startup and saved upon exit.

--autouservars

Controls automatic loading and saving of the global user variables

--bad-data

Controls how bad data about to be sent to the server is handled.

--batch-mode

Indicates the interactive shell should not be used.

--binary-display-maxlen

Maximum number of bytes o display of binary data for a YANG object

--break-key-mode

Controls the behavior when the break key (Control C) is pressed

--callhome-address

IP address to use to listen for CallHome SSH requests

--callhome-enabled

Enable or disable the IETF Call Home protocol

--callhome-port

TCP port number to use to listen for NETCONF over SSH CallHome requests

--callhome-tls-port

TCP port number to use to listen for NETCONF over TLS CallHome requests

--callhome-user

One or more name of a configured user entries to use for Call Home connections

--check-output

Controls whether YANG <rpc> validation is done

--check-output-error

Controls whether YANG <rpc> validation errors are treated as errors or warnings

--check-replies

Controls whether YANG <rpc-reply> validation is done

--check-replies-error

Controls whether YANG <rpc-reply> validation errors are treated as errors or warnings

--config

Specifies the configuration file to use for parameters.

--config-autosave

Controls how edits in config term mode are saved to NV-storage if the server supports the :startup capability.

--config-commit-mode

If 'true' then edits done in config mode will be made to the candidate datastore if possible. The edits will not be committed to the running datastore automatically.

--config-edit-mode

Controls how edits are applied during configuration mode

--datapath

Sets the data file search path.

--default-module

Specifies the default module to use to resolve identifiers.

--deviation

Species one or more YANG modules to load as deviations.`

--disable-command

Specifies a top-level command that should be disabled and not visible or available to a user. If the value does not contain a module name prefix, then the command will be disabled in all modules.

--display-mode

Specifies how values should be displayed.

--echo-notif-loglevel

Specifies the log-level needed to echo unregistered notifications to the log and/or STDOUT.

--echo-notifs

Specifies whether unregistered notifications will be output to the log or STDOUT.

--echo-replies

Controls whether RPC replies will be displayed in the log output, if log-level >= 'info'

--encoding

Controls the desired RESTCONF encoding format.

--entry-point

RESTCONF entry point. Use this string instead of retrieving the XRD from the RESTCONF server to discover the entry point

--feature-disable

Leaf list of features to disable

--feature-enable

Specifies a feature that should be enabled

--feature-enable-default

Specifies if a feature should be enabled or disabled by default

--fill-optional

Specifies the default value for the –optional flag for the operations that fill YANG datastore contents

--fixorder

Controls whether PDUs are changed to canonical order before sending them to the server.

--force-target

Controls whether the candidate or running configuration datastore will be used as the default edit target, when both are supported by the server.

--handle-bad-reply

Controls the behavior of the XML parser and dictates how a bad RPC reply will be handled.

--help

Get program help.

--help-mode

Adjust the help output (--brief or --full).

--help-width

Width of help text line for '?' help key output

--history-file

Specifies the libtecla command line history file to use

--home

Override the $HOME environment variable.

--ignore-missing-vars

Specifies whether a missing variable in a data template is an error or the variable expands to an empty string

--indent

Specifies the indent count to use when writing data.

--insecure-ok

Specifies if unverified client certificates will be accepted (DEBUG only)

--keepalive-interval

Specifies the keepalive message interval. NOT IMPLEMENTED.

--leaflist-multi-line

Specifies if multiple leaf-lists allowed in 1 line in config mode

--log

Specifies the log file to use instead of STDOUT. See the YumaPro User Manual for a general discussion of logging.

--log-append

Controls whether a log file will be reused or overwritten.

--log-backtrace

Append stack trace information to log messages.

--log-backtrace-detail

Add additional (compiler/OS dependent) detail to stack trace information.

--log-backtrace-level

Specify message level(s) for which stack trace information will be generated.

--log-backtrace-stream

Include stack trace information in the specified output stream(s

--log-console

Specifies that log output will be sent to STDOUT after being sent to log file and/or syslog

--log-header

Include additional information (level/date/time) with log message.

--log-highres-datetime

Include a microseconds field in the log timestamps.

--log-level

Specifies verbosity level of log message output

--log-mirroring

Synonym for log-console.

--log-stderr

Specifies that error level log messages will be sent to STDERR.

--log-suppress-ctrl

If present, strip certain control characters from output in order to modify log formatting.

--log-syslog

Send log message output to the syslog daemon.

--log-syslog-level

Sets the syslog debug logging level filter for output to the syslog file

--match-names

Match mode to use for UrlPath searches

--message-indent

The number of spaces to indent for each level of output in a protocol message, e.g. NETCONF request.

--modpath

Sets the module search path.

--module

Specifies one or more YANG modules to load upon startup.

--ncport

Specifies the NETCONF server port number to use in the connect command.

--no-aliases

Disables the alias substitution feature.

--no-config

Specifies that the default configuration file should not be loaded if it exists. Not a configuration file parameter.

--no-password

Specifies that keys will be used instead of a password. Ignored if used as a configuration file parameter.

--optional

Specifies the default value of the $$optional variable. This will affect all input, not just YANG datastore contents. Use with caution!

--password

Specifies the password to use in the connect command.

--private-key

Contains the file path specification for the file containing the client-side private key.

--prompt

Set a complete custom prompt for yp-shell

--prompt-name

Customize a prompt name for yp-shell.

--prompt-type

Selects the type of prompt string that will be used in interactive mode.

--protocols

Controls which NETCONF protocol versions will be enabled. Ignored if used in a configuration file.

--public-key

Contains the file path specification for the file containing the client-side public key

--restrict-edit-mode

Controls whether an 'restrict edit mode' will be supported for yp-shell.

--runpath

Sets the executable file search path.

--run-command

Specifies the command to run at startup time.

--run-script

Specifies the script to run at startup time.

--save-session-vars

Specifies if session variables will be saved when the program exits.

--script-input

Controls whether the program will stop for input when running a script in interactive mode.

--server

Specifies the server address to use in the connect command.

--server-commands

Specifies whether RPC operations learned from server YANG modules will be added as a command available to the user.

--shell-command

The shell program to invoke for the run-shell command.

--ssl-certificate

Contains the file path specification for the file containing the client-side SSL certificate.

--ssl-fallback-ok

If true then an attempt to establish a plain TCP connection will be made if an SSL connection cannot be made.

--ssl-key

Contains the file path specification for the file containing the client-side SSL key

--ssl-trust-store

Contains the file path specification for the file containing the client-side ssl trust-store, or the path specification for the directory to use for finding trusted certificates`

--subdirs

Specifies whether child sub-directories should be searched when looking for files.

--tcp-connect-timeout

The number of seconds to wait for the TCP connect function to finish

--term-length

Specifies the number of lines that should be printed per page if paginated output is used.

--test-suite-file

Specifies the name of the test suite file to load if --autotest=true.

--time-rpcs

Measure the round-trip time of each <rpc> request and <rpc-reply> at the session level.

--time-rpcs-stats

Save rpc statistics to the specified or default statistics file if the time-rpcs variable is also true.

--time-rpcs-stats-file

Save rpc statistics to the specified file if the --time-rpc-stats and time-rpcs variables are true.

--timeout

Specifies the timeout to use in the connect command.

--transport

Specified the transport protocol to use (ssh, tcp, or tpc-ncx)

--use-data-templates

Controls whether data templates are enabled

--use-rawxml

Controls how file result variables will be read. If true then the YANG object template will not be used when parsing the XML file.

--use-session-vars

Controls how global variables will be handled when set from the context of a named session. If true then session-specific variables will be used.

--use-traceid

Controls whether the 'trace-id' attribute will be set in the RPC calls or not. By default, 'trace-id' attribute is disabled.

--use-xmlheader

Specifies how file result variables will be written for XML files. Controls whether the XML preamble header will be written or not.

--user

The default user name for NETCONF sessions.

--uservars-file

Specifies the global user variable files to load.

--version

Prints the program version and exits.

--warn-error

Treat all warnings as errors

--warn-idlen

Controls how identifier lengths are checked.

--warn-linelen

Controls how line lengths are checked.

--warn-off

Suppresses the specified warning number.

--warn-up

Elevates the specified warning number to an error

--wildcard-keys

Enable wildcards on key leaf values

--with-enable-mode

Controls whether an enable mode will be supported for yp-shell.

--with-notif-commands

Controls whether notification commands are available in yp-shell

--with-ocpattern

Controls whether OpenConfig pattern syntax will be checked

--with-term-msg

Controls whether Terminal Diagnostic events are supported

--yangmap

Specifies a yangmap XML file that should be loaded into the program

--yumapro-home

Specifies the $YUMAPRO_HOME project root to use when searching for files.