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:
- <edit-config> high level functions:
  - create
  - delete
  - insert
  - merge
  - replace
  - remove
- <get> and <get-config> high-level functions:
  - sget
  - sget-config
  - xget
  - xget-config
- NMDA <get-data> high-level functions:
  - sget-data
  - xget-data
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.

It is also possible to invoke system commands using the run-shell command.

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
callhome-server	Start or stop the Call Home server
callhome-user	Add or remove a Call Home user
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.

System Commands

If the --allow-shell parameter is set to 'true'. then the run-shell command will be enabled. The default is 'false'.

For 'yp-shell', the --ypshell-exec-ok parameter must also be set to 'true'. The default is 'false'.

This command allows access to a shell command to use, which can be configured with the --shell-command parameter. The default shell is /bin/bash.

The 'runpath' is searched for a matching script name, according to the $YUMAPRO_RUNPATH environment variable, or the --runpath CLI parameter, or the default File Search Paths.

Example: Ping command

Install the following script in the runpath, e.g. ~/scripts.ping.sh.

ping -c5 $1

Start yangcli-pro

> yangcli-pro --allow-shell=true

Invoke the shell with the script:

 > run-shell ping.sh P1=127.0.0.1
 PING 127.0.0.1 (127.0.0.1) 56(84) bytes of data.
 64 bytes from 127.0.0.1: icmp_seq=1 ttl=64 time=0.095 ms
 64 bytes from 127.0.0.1: icmp_seq=2 ttl=64 time=0.053 ms
 64 bytes from 127.0.0.1: icmp_seq=3 ttl=64 time=0.054 ms
 64 bytes from 127.0.0.1: icmp_seq=4 ttl=64 time=0.062 ms
 64 bytes from 127.0.0.1: icmp_seq=5 ttl=64 time=0.060 ms

 --- 127.0.0.1 ping statistics ---
 5 packets transmitted, 5 received, 0% packet loss, time 4090ms
 rtt min/avg/max/mdev = 0.053/0.064/0.095/0.015 ms

 >

It is possible to install an alias to simplify the operation.

> alias ping='run-shell script=ping.sh P1 `

Now the command 'ping' can be used directly:

 > ping 127.0.0.1
 PING 127.0.0.1 (127.0.0.1) 56(84) bytes of data.
 64 bytes from 127.0.0.1: icmp_seq=1 ttl=64 time=0.068 ms
 64 bytes from 127.0.0.1: icmp_seq=2 ttl=64 time=0.057 ms
 64 bytes from 127.0.0.1: icmp_seq=3 ttl=64 time=0.052 ms
 64 bytes from 127.0.0.1: icmp_seq=4 ttl=64 time=0.014 ms
 64 bytes from 127.0.0.1: icmp_seq=5 ttl=64 time=0.056 ms

 --- 127.0.0.1 ping statistics ---
 5 packets transmitted, 5 received, 0% packet loss, time 4079ms
 rtt min/avg/max/mdev = 0.014/0.049/0.068/0.018 ms

 >

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 2^nd 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:

Read-only system variables
Read-write system variables
Read-write global user variables (saved in $HOME/.yuma directory)
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
$$match-names-exec-mode	--match-names-exec-mode 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 Call Home SSH or TLS requests
--callhome-enabled	Enable or disable the IETF Call Home protocol
--callhome-port	TCP port number to use to listen for NETCONF over SSH Call Home requests
--callhome-tls-port	TCP port number to use to listen for NETCONF over TLS Call Home 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
--confirm-data-retries	Sets the number of retry attempts allowed to verify a Confirmed Parameter
--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
--hide-command	Specifies a top-level command that should be enabled but not visible to a user.
--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 in config mode
--match-names-exec-mode	Match mode to use for UrlPath searches in exec mode
--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.
--show-headers	Show or suppress message headers in server response display
--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-off-yang	Suppresses all YANG warnings
--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
--ypshell-exec-ok	Specifies if exec type commands are available in the yp-shell program
--yumapro-home	Specifies the $YUMAPRO_HOME project root to use when searching for files.