YumaPro yangcli-pro Manual

Transcription

1 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 Version

2 Table Of Contents 1 Preface Legal Statements Additional Resources WEB Sites Mailing Lists Conventions Used in this Document yangcli-pro User Guide Introduction Features Starting yangcli-pro Stopping yangcli-pro Statements Commands Variables Files Scripts Configuration Mode Editing Configuration Parameter List Invoking Commands Command Prompt Command Name ncx:default-parm Extension Parameter Mode Escape Commands Using Inline XML or JSON Data Using XPath Expressions Special Parameter Handling Command Completion Command Line Editing Command History Command Responses Controlling Terminal Output Pipe Commands Pagination Display Mode NETCONF Device Configuration Saving Devices Multiple Devices Saving the Configured Devices Loading Additional Configured Devices Displaying the Configured Devices Displaying Devices Saved Device Configuration File Format Device Configuration File Example NETCONF User Configuration Creating New Users Saving Users Multiple Users Saving the Configured Users Loading Additional Configured Users Displaying the Configured Users...59 Version Page 2

3 2.5.7 Displaying Users Saved User Configuration File Format User Configuration File Example NETCONF Session Configuration Saving Sessions Multiple Sessions Changing the Active Session Saving the Configured Sessions Loading Additional Configured Sessions Displaying the Configured Sessions Displaying Sessions Terminating a Named Session Saved Session Configuration File Format Session Configuration File Example NETCONF Group Configuration Create group List group Delete group Add group Remove Group Show Group Connect Group Help Group Saving Groups Changing the Active group Using NETCONF Sessions Connection Startup Screen Server Tailored Context Retrieving Data Modifying Data Using Notifications Configuration Parameters That Affect Sessions Trouble-shooting NETCONF Session Problems Automated Testing Test Templates YANG File Defining Test Templates Example Test File Call Home Server Call Home Configuration Call Home Accept Session Procedure Command Reference action alias aliases auto-test cache cd clear close-session commit config config-commit Version Page 3

4 connect copy-config create create-subscription device-cfg devices-cfg delete delete-config discard-changes edit-config elif else end eval eventlog exit fill get get-config get-locks get-my-session get-schema group help history if insert kill-session list load lock log-debug log-error log-info log-warn merge mgrload no-op nvsave pwd quit recall record-test release-locks remove replace restart run save session session-cfg sessions-cfg Version Page 4

5 set-log-level set-my-session sget sget-config show shutdown sleep start-rpc-timing start-session start-timer stop-rpc-timing stop-session stop-timer terminal test-suite unlock unset user-cfg users-cfg uservars validate while xget xget-config CLI Reference aliases-file alt-names ask-password autoaliases autocomp autoconfig autodevices autohistory autoload autoload-cache autoload-get autoload-save-cache auto-keepalive auto-reconnect auto-reconnect-interval auto-reconnect-max autonotif autonvsave autosessions autotest autousers autouservars bad-data batch-mode callhome-address Version Page 5

6 callhome-enabled callhome-port callhome-tls-port callhome-user check-output check-output-error check-replies check-replies-error config config-autosave config-commit-mode config-edit-mode datapath default-module disable-command deviation display-mode echo-notif-loglevel echo-notifs echo-replies feature-disable feature-enable feature-enable-default fill-optional fixorder force-target help help-mode help-width home ignore-missing-vars indent insecure-ok keepalive-interval log log-append log-backtrace log-backtrace-detail log-backtrace-level log-backtrace-stream log-console log-header log-level log-mirroring log-stderr log-suppress-ctrl log-syslog log-syslog-level Version Page 6

7 match-names message-indent modpath module ncport no-aliases no-config optional password private-key prompt-name prompt-type protocols public-key runpath run-command run-script save-session-vars server server-commands subdirs term-length test-suite-file time-rpcs time-rpcs-stats time-rpc-stats-file timeout transport use-data-templates use-rawxml use-traceid use-session-vars use-xmlheader user uservars-file version warn-error warn-idlen warn-linelen warn-off warn-up with-ocpattern yumapro-home Version Page 7

8 1 Preface 1.1 Legal Statements Copyright , Andy Bierman, All Rights Reserved. Copyright , YumaWorks, Inc., All Rights Reserved. 1.2 Additional Resources This document assumes you have successfully set up the software as described in the printed document: YumaPro Installation Guide Other documentation includes: YumaPro API Quickstart Guide YumaPro Quickstart Guide YumaPro User Manual YumaPro netconfd-pro Manual YumaPro yangdiff-pro Manual YumaPro yangdump-pro Manual YumaPro Developer Manual YumaPro ypclient-pro Manual YumaPro yp-system API Guide YumaPro yp-show API Guide YumaPro Yocto Linux Quickstart Guide YumaPro yp-snmp Manual To obtain additional support you may contact YumaWorks technical support department: WEB Sites YumaWorks Offers support, training, and consulting for YumaPro. Netconf Central Yang Central Free information on NETCONF and YANG, tutorials, on-line YANG module validation and documentation database Version Page 8

9 Free information and tutorials on YANG, free YANG tools for download NETCONF Working Group Wiki Page Free information on NETCONF standardization activities and NETCONF implementations NETCONF WG Status Page IETF Internet draft status for NETCONF documents libsmi Home Page Free tools such as smidump, to convert SMIv2 to YANG Mailing Lists NETCONF Working Group Technical issues related to the NETCONF protocol are discussed on the NETCONF WG mailing list. Refer to the instructions on the WEB page for joining the mailing list. NETMOD Working Group Technical issues related to the YANG language and YANG data types are discussed on the NETMOD WG mailing list. Refer to the instructions on the WEB page for joining the mailing list. 1.3 Conventions Used in this Document The following formatting conventions are used throughout this document: Documentation Conventions Convention --foo <foo> foo $FOO $$foo some text some text Description CLI parameter foo XML parameter foo yangcli-pro command or parameter Environment variable FOO yangcli-pro global variable foo Example command or PDU Plain text Version Page 9

10 2 yangcli-pro User Guide YumaPro yangcli-pro Manual Program Components 2.1 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 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 Version Page 10

11 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 Version Page 11

12 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 Version Page 12

13 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 Starting yangcli-pro The current working directory in use when yangcli-pro is invoked is important. It is most convenient to run yangclipro 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 Version Page 13

14 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 (--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 --server=myserver.example.com \ --user=andy --password=yangrocks \ --run-script=mytestscript To automatically connect to a server, run a script in non-interactive mode, and then exit the program, add the --batch-mode and --run-script parameters to the connection parameters. The --runpath parameter can also be entered, if needed. yangcli-pro --server=myserver.example.com \ --user=andy --password=yangrocks \ --run-script=mytestscript --batch-mode To automatically connect to a server, and run a single command instead of a script, and then exit, use the --run-command parameter instead of the --run-script parameter. The --batch-mode parameter can be left out to remain in the current session (in interactive mode) after the command is invoked. yangcli-pro --server=myserver.example.com \ --user=andy --password=yangrocks \ --batch-mode --run-command= sget /system Stopping yangcli-pro Version Page 14

15 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: command variable assignment yangcli-pro Statements type description example invoke a local command and/or send an <rpc> to the server set a user variable to some value sget /system $system = sget /system file assignment set the contents of a file to some = $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). Note: More statement types will be available in the next release 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 2 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. Version Page 15

16 Local Commands command alias aliases auto-test cache cd clear config connect device-cfg devices-cfg elif else end eval eventlog exit fill group help history if list log-debug log-error log-info log-warn mgrload nvsave pwd quit recall record-test run session session-cfg description Show or set a specific yangcli-pro command alias Manage the yangcli-pro command aliases Run automatic edit testing on the specified session Clear 1 or all entries from the YANG module cache Change the current working directory Clear the screen Enter the configuration mode for the current session Connect to a server and start a NETCONF session Access a named device configuration Access the named device configuration file Start an 'else-if' conditional block Start an 'else' conditional block End an 'if' or 'while' block Evaluate an XPath expression View or clear the notification event log Exit configuration mode for the current session Fill a user variable Manage the session groups. Get context-sensitive help Manage the command history buffer Start an 'if' conditional block List modules, objects, or other properties of the session Log a debug message Log an error message Log an info message Log a warning message Load a YANG file into the client only Save the running datastore to the startup datastore Print the current working directory Exit the program Recall a line from the command history buffer Record commands and responses for a regression test Run a script Set the current session Access a named session configuration Version Page 16

17 session sessions-cfg show sleep start-rpc-timing stop-session stop-timer terminal test-suite user-cfg users-cfg update-config unset uservars while Set the current session Access the named session configuration file Show variables and objects currently available Sleep for a number of seconds (for use in scripts) Start <rpc> timing mode and save statistics to a file Stop a named session Stop a script timer and display the elapsed time Set the terminal length Access a configured unit-test suite for automated testing Access a named user configuration Access the named user configuration file Update the shadow configuration for the current session< Remove a command alias from memory Manage the yangcli-pro user variables Start a 'while' conditional loop block Version Page 17

18 The following table shows the standard NETCONF protocol operations that are directly available for use, depending on the capabilities of the server. Standard NETCONF Commands command cancel-commit close-session commit copy-config create-subscription delete-config discard-changes edit-config get get-config get-schema kill-session lock unlock validate description Cancel the current confirmed commit procedure Close the current NETCONF session Make the candidate database be the running config Copy an entire NETCONF database Start receiving NETCONF notifications Delete an entire NETCONF database Discard any edits in the candidate database Alteration of the target database Filtered retrieval of state data and running config Filtered retrieval of any NETCONF database Get a data model definition file from the server Force close another NETCONF session Lock a NETCONF database that is currently unlocked Unlock a NETCONF database that is currently locked Validate the contents of a NETCONF database The following yangcli-pro commands are available for simplified access to standard NETCONF operations Custom NETCONF Commands command action create delete get-locks insert merge release-locks remove replace save description Invoke a YANG 1.1 <action> Invoke an <edit-config> create operation Invoke an <edit-config> delete operation Lock all the databases with the <lock> operation Invoke an <edit-config> YANG insert operation Invoke an <edit-config> merge operation Unlock all the locked databases with the <unlock> operation Invoke an <edit-config> remove operation Invoke an <edit-config> replace operation Save the current edits on the server in NV-storage Version Page 18

19 sget sget-config xget xget-config Invoke a <get> operation with a subtree filter Invoke a <get-config> operation with a subtree filter Invoke a <get> operation with an XPath filter Invoke a <get-config> operation with an XPath filter The following table shows the extended NETCONF protocol operations that are available on the netconfd-pro server only. Extended netconfd-pro Commands command get-my-session load no-op restart set-log-level set-my-session shutdown description Retrieve session customization parameters Load a module into the server. No operation. Restart the server. Set the server logging verbosity level. Set session customization parameters. Shutdown the server. The following table shows the special configuration mode commands and keywords. They are only allowed in configuration mode. Configuration Mode Commands command apply exit do no return description Apply any pending edits to the current session Return to the parent mode and apply and pending edits Run a command in configuration mode Prefix to configuration mode command used to delete a node Return to normal mode from Confing mode without applying ny edits 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). Version Page 19

20 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: 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-name> $$<variable-name> $<variable-name> $<variable-name> Variable Syntax syntax description example Left hand side: set the global variable to some value Right hand side: access the value of a global variable Left hand side: set the local variable to some value Right hand side: access the value of any variable with this name (try local, then global) $$saved_get = get fill --target=\ $$mytarget $myloglevel = \ $$log-level $myuser = $user The following table shows the unix environment variables that are available as read-only global variables in yangclipro. These variables are set once when the program is started, and cannot be used in the the left hand side of an assignment statement. Read-only system variables variable $$HOME $$HOSTNAME $$LANG $$PWD $$SHELL $$USER description the HOME environment variable the HOST or HOSTNAME environment variable the LANG environment variable the PWD environment variable, when yangcli-pro was invoked the SHELL environment variable the USER environment variable Version Page 20

21 $$YUMAPRO_DATAPATH $$YUMAPRO_HOME $$YUMAPRO_MODPATH $$YUMAPRO_RUNPATH the YUMAPRO_DATAPATH environment variable the YUMAPRO_HOME environment variable the YUMAPRO_MODPATH environment variable the YUMAPRO_RUNPATH environment variable The following table shows the CLI configuration parameters that can be read or changed (but not deleted). If a particular parameter was not set during program invocation, then the associated variable will contain the empty string. Read-write system variables variable description $$aliases-file the --aliases-file configuration parameter $$alt-names the alt-names configuration parameter $$ask-password The ask-password configuration parameter $$autoaliases the --autoaliases configuration parameter $$autocomp the --autocomp configuration parameter $$autoconfig the --autoconfig configuration parameter $$autodevices the --autodevices configuration parameter $$autohistory the --autohistory configuration parameter $$autoload the --autoload configuration parameter $$autoload-cache the --autoload-cache configuration parameter $$autoload-save-cache the autoload-save-cache configuration parameter $$auto-keepalive the auto-keepalive configuration parameter $$auto-reconnect the -auto-reconnect configuration parameter $$auto-reconnect-interval the --auto-reconnect-interval configuration parameter $$auto-reconnect-max the --auto-reconnect-max configuration parameter $$autoload-get the --autoload-get configuration parameter $$autonotif the --autonotif configuration parameter $$autonvsave the autonvsave configuration parameter $$autosessions the --autosessions configuration parameter $$autotest the --autotest configuration parameter $$autousers the --autousers configuration parameter $$autouservars the --autouservars configuration parameter $$baddata the --baddata configuration parameter $$check-output the --check-output configuration parameter $$check-output-error the --check-output-error configuration parameter $$check-replies the --check-replies configuration parameter $$check-replies-error the --check-replies-error configuration parameter $$config-autosave the --config-autosave configuration parameter Version Page 21

22 $$config-commit-mode $$config-edit-mode $$default-module $$default-operation $$display-mode $$echo-notif-loglevel $$echo-notifs $$echo-replies $$error-option $$fill-optional $$fixorder $$help-width $$ignore-missing-vars $$indent $$keepalive-interval $$log-level $$match-names $$message-indent $$optional $$prompt-type $$save-session-vars $$script-input $$server $$ssl-fallback-ok $$term-length $$test-option $$test-suite-file $$time-rpcs $$time-rpcs-stats $$time-rpcs-stats-file $$timeout $$use-data-templates $$use-rawxml $$use-traceid $$use-sessionvars $$use-xmlheader $$user the --config-commit-mode configuration parameter the --config-edit-mode configuration parameter the --default-module configuration parameter the <default-operation> parameter for the <edit-config> operation the --display-mode configuration parameter the --echo-notif-loglevel configuration parameter the --echo-notifs configuration parameter the --echo-replies configuration parameter the default <error-option> parameter for the <edit-config> the fill-optional CLI parameter the --fixorder configuration parameter the help-width configuration parameter the ignore-missing-vars configuration parameter the indent configuration parameter The -keepalive-interval configuration parameter the --log-level configuration parameter the match-names configuration parameter the --message-indent configuration parameter the --optional configuration parameter the --prompt-type configuration parameter the --save-session-vars configuration parameter the --script-input configuration parameter the --server configuration parameter the ssl-fallback-ok configuration parameter the term-length configuration parameter the <test-option> parameter for the <edit-config> operation the --test-suite-file configuration parameter the time-rpcs configuration parameter the --time-rpc-stats configuration parameter the --time-rpc-stats-file configuration parameter the --timeout configuration parameter the --use-data-templates configuration parameter the --use-rawxml configuration parameter the --use-traceid configuration parameter the --use-sessionvars configuration parameter the use-xmlheader configuration parameter the --user configuration parameter Version Page 22

23 $$uservars-file $$with-defaults the --uservars-file configuration parameter the --with-defaults 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. = 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 yangclipro will strip off the outermost XML (if needed) to save the requested file as a pure text file. Otherwise, the file will be saved in XML format. The display mode set by the user can affect XML output. If the display mode i s'xml-nons' then XML without namespace (xmlns) attributes will be generated instead of normal XML. Version Page 23

24 Note: The --display-mode configuration parameter, and $$display-mode system variable, only affect the output and display of data in the yangcli-pro program. NETCONF protocol messages are always sent in 'xml' mode. 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. Version Page 24

25 Scripts can be called recursively, but a stop condition needs to be used to break the recursion (e.g., call the script from within a conditional code block. Conditional Command Blocks The 'if', 'elif', 'else', and 'end' commands are used to create an 'if command sequence'. Any other commands that appear between these commands are part of a conditional command block. These blocks can be nested. The current conditional state is inherited, so an if command sequence within a false conditional block will not be executed. A block can contain zero or more command lines, These command work exactly like an 'if' expression within a program language such as Python. Note that indentation is not significant, but it may be used to make scripts more readable. The 'if' command starts a new if-command sequence. It is followed by a conditional command block. This block ends when an 'elif', 'else', or 'end' command within the same if command block is encountered. At most, only one conditional code block within the if command sequence will be executed. Once a conditional command block has been exectuted, any remaining blocks will be skipped. All user and system variables that are available to the current script run level can be used within the XPath expressions for determining the conditional block state (true or false). Conditional Command Loop Blocks The 'while' and 'end' commands are used to create an 'while loop sequence'. Any other commands that appear between these commands are part of a conditional command loop block. These blocks can be nested. The current conditional state is inherited, so a while loop sequence within a false conditional block will not be executed. A block can contain zero or more command lines, The loop condition can be a constant expression. The maxloops parameter will prevent infinite looping, and can be utilized to use the while loop sequence as a simple 'for' loop, iterating a specific number of times. All user and system variables that are available to the current script run level can be used within the XPath expressions for determining the conditional block state (continue or terminate loop). Sample Script 1 The following script does not do any useful work. It is provided to demonstrate some simple constructs. $x = 0 while '$x < 2' # this is a comment log-info 'start 1' $x = eval '$x + 1' $y = 0 while '$y < 4' log-info 'start 2' $y = eval '$y + 1' if "module-loaded('test')" Version Page 25

26 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 Sample Script 2 The following script demonstrates how to run multiple edits on ietf-interface.yang data module: $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 In addition to the normal NETCONF low-level and high-level editing commands, there is also a configuration mode similar to a router CLI. This mode can be used to edit YANG datastore nodes with a simplified interface. Configuration 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. In configuration mode, data node names can be abbreviated just like RPC operation parameter names. Enter Configuration Mode To enter configuration mode, use the 'config' command: mysession> config term Version Page 26

27 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)# 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> Version Page 27

28 Creating or modifying server database parameters YumaPro yangcli-pro Manual 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 command is given. To force all pending edits to be sent to the current session, the apply command can be used within a given context level. 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 In order to enter normal yangcli-pro commands while in configuration mode, the 'do' prefix is used. Only a limited set of commands can be accessed from configuration mode in this manner. Version Page 28

29 mysession# do show session [session info shown] mysession# Configuration Parameter List The following configuration parameters are used by yangcli-pro. Refer to the CLI Reference for more details. --aliases-file --alt-names parameter --ask-password --autoaliases --autocomp --autoconfig --autodevices --autohistory --autoload -autoload-cache -autoload-get --autonotif --autonvsave --autosessions yangcli-pro CLI Parameters description Specifies the command aliases file to use. Controls whether alternate names will be checked for UrlPath searches. Controls whether the 'connect' command will prompt for password parameter (if it is not provided). Controls automatic loading and saving of the command aliases Controls whether partial commands are allowed or not. Controls whether the running configuration will be retrieved automatically for active sessions. Controls whether saved device configurations are loaded at startup and saved upon exit. Controls whether th command line history buffer will be automatically loaded at startup and saved on exit. Controls whether modules used by the server will be loaded automatically, as needed. Controls whether the modules retrieved with the <get-schema> operation are cached for use by the running instance of yangcli-pro. Controls whether the <get> operation will be used to retrieve the /netconf-state/schemas sub-tree. Controls whether notifications will automatically be enabled when a session starts. Controls whether the 'save' and 'apply' commands will NV-save the configuration changes or not. Controls whether saved session configurations are loaded at startup and saved upon 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. Version Page 29

30 --autouservars --bad-data --batch-mode --callhome-address --callhome-enabled --callhome-port --callhome-tls-port --callhome-user --check-output --check-output-error --check-replies --check-replies-error --config --config-autosave --config-commit-mode --config-edit-mode --datapath --default-module --deviation --disable-command --display-mode --echo-notif-loglevel --echo-notifs --echo-replies --feature-disable --feature-enable --feature-enable-default --fill-optional Controls automatic loading and saving of the global user variables Controls how bad data about to be sent to the server is handled. Indicates the interactive shell should not be used. IP address to use to listen for CallHome SSH requests Enable or disable the IETF Call Home protocol TCP port number to use to listen for NETCONF over SSH CallHome requests TCP port number to use to listen for NETCONF over TLS CallHome requests Name of a configured user entry to use for Call Home connections Controls whether YANG <rpc> validation is done Controls whether YANG <rpc> validation errors are treated as errors or warnings Controls whether YANG <rpc-reply> validation is done Controls whether YANG <rpc-reply> validation errors are treated as errors or warnings Specifies the configuration file to use for parameters. The --no-config option can be used instead to prevent the default config file from being used. Controls how edits in config term mode are saved to NV-storage if the server supports the :startup capability. Controls how edits are committed in data store during configuration mode. Controls how edits are applied during configuration mode Sets the data file search path. Specifies the default module to use to resolve identifiers. Species one or more YANG modules to load as deviations.` 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. Specifies how values should be displayed. Specifies the log-level needed to echo unregistered notifications to the log and/or STDOUT. Specifies whether unregistered notifications will be output to the log or STDOUT. Controls whether RPC replies will be displayed in the log output, if log-level >= 'info' Leaf list of features to disable Specifies a feature that should be enabled Specifies if a feature should be enabled or disabled by default Specifies the default value for the optional flag for the operations that fill YANG datastore contents Version Page 30

31 --fixorder --force-target --help --help-mode --help-width --home --ignore-missing-vars --indent --insecure-ok --log --log-append --log-backtrace --log-backtrace-detail --log-backtrace-level --log-backtrace-stream --log-console --log-header --log-level --log-mirroring --log-stderr --log-suppress-ctrl Controls whether PDUs are changed to canonical order before sending them to the server. Controls whether the candidate or running configuration datastore will be used as the default edit target, when both are supported by the server. Get program help. Adjust the help output (--brief or --full). Width of help text line for '?' help key output Override the $HOME environment variable. Specifies whether a missing variable in a data template is an error or the variable expands to an empty string Specifies the indent count to use when writing data. Specifies if unverified client certificates will be accepted (DEBUG only) Specifies the log file to use instead of STDOUT. See the YumaPro User Manual for a general discussion of logging. Controls whether a log file will be reused or overwritten. Append stack trace information to log messages. Add additional (compiler/os dependent) detail to stack trace information. Specify message level(s) for which stack trace information will be generated. Include stack trace information in the specified output stream(s Specifies that log output will be sent to STDOUT after being sent to log file and/or syslog (assumes log=file and/or --log-syslog are present). Include additional information (level/date/time) with log message. Specifies verbosity level of log message output Synonym for log-console. Specifies that error level log messages will be sent to STDERR. If present, strip certain control characters from output in order to modify log formatting. --log-syslog Send log message output to the syslog daemon. --match-names --message-indent --modpath --module --ncport --no-config Match mode to use for UrlPath searches The number of spaces to indent for each level of output in a protocol message, e.g. NETCONF request. Sets the module search path. Specifies one or more YANG modules to load upon startup. Specifies the NETCONF server port number to use in the connect command. Specifies that the default configuration file should not be loaded if it exists Version Page 31

32 --no-aliases --optional --password --private-key --prompt-name --protocols --public-key --runpath --run-command --run-script --save-session-vars --script-input --server --server-commands --subdirs --term-length --test-suite-file Disables the alias substitution feature. Specifies the default value of the $$optional variable. THis will affect all input, not just YANG datastore contents. Use with caution! Specifies the password to use in the connect command. Contains the file path specification for the file containing the clientside private key. Customize a prompt name for yp-shell. Controls which NETCONF protocol versions will be enabled Contains the file path specification for the file containing the clientside public key. Sets the executable file search path. Specifies the command to run at startup time. Specifies the script to run at startup time. Specifies if session variables will be saved when the program exits. Controls whether the program will stop for input when running a script in interactive mode. Specifies the server address to use in the connect command. Specifies whether RPC operations learned from server YANG modules will be added as a command available to the user. Specifies whether child sub-directories should be searched when looking for files. Specifies the number of lines that should be printed per page if paginated output is used. The terminal length command can also be used for the same purpose. Specifies the name of the test suite file to load if --autotest=true. The default value is $HOME/.yumapro/yangcli_pro_tests.conf --time-rpcs Measure the round-trip time of each <rpc> request and <rpc-reply> at the session level. --time-rpcs-stats --time-rpcs-stats-file --timeout --transport --use-data-templates --use-rawxml --use-traceid --use-session-vars Save rpc statistics to the specified or default statistics file if the timerpcs variable is also true. Save rpc statistics to the specified file if the --time-rpc-stats and timerpcs variables are true. The default value is $HOME/yangcli_pro_rpc_stats.txt Specifies the timeout to use in the connect command. Specified the transport protocol to use (ssh, tcp, or tpc-ncx) Controls whether data templates are enabled Controls how file result variables will be read. If true then the YANG object template will not be used when parsing the XML file. Controls whether the 'trace-id' attribute will be set in the RPC calls or not. By default, 'trace-id' attribute is disabled. 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. Version Page 32

33 --use-xmlheader --user --uservars-file --version --warn-error --warn-idlen --warn-linelen --warn-off --warn-up --with-ocpattern --yumapro-home Specifies how file result variables will be written for XML files. Controls whether the XML preamble header will be written or not. The default user name for NETCONF sessions. Specifies the global user variable files to load. Prints the program version and exits. Treat all warnings as errors Controls how identifier lengths are checked. Controls how line lengths are checked. Suppresses the specified warning number. Elevates the specified warning number to an error Controls whether OpenConfig pattern syntax will be checked Specifies the $YUMAPRO_HOME project root to use when searching for files. 2.2 Invoking Commands Commands can be entered with parameters: in one continuous line session1> merge target=/toaster/toastcontrol --value= down in several lines (using line continuation) session1> merge target=/toaster/toastcontrol \ more> --value= down interactively prompted for each parameter session1> merge (will be prompted for target and value) a combination of the above session1> merge target=/toaster/toastcontrol (will be prompted for value) Version Page 33

34 When a command is entered, and the yangcli-pro script interpreter is running in interactive mode (--batch-mode not active), then the user will be prompted for any missing mandatory parameters. If the --optional parameter is present (or the $$optional system variable is set to 'true'), then the user will be prompted for any optional parameters that are missing. A command has the basic form: <name (QName)> <parameter (any YANG type)>* The command name is a qualified name matching the name used in the YANG rpc statement. This is followed by zero or more parameters (in any order). A command parameter has the same syntax as a CLI configuration parameter. The command name syntax is described below. An un-escaped end-of-line character ('enter key') terminates command line input Command Prompt The yangcli-pro command prompt changes, depending on the context. Idle Mode: If the script interpreter is idle and there is no NETCONF session active, then the prompt is simply a 'less than' sign: > If the script interpreter is idle and the default NETCONF session active, then the prompt is of the form <user>@<server>', depending on the parameters used in the connect command. Note that the <server> portion of the prompt can be configured in yp-shell, using the prompt-name CLI parameter. andy@myserver> If a named session is active, then the '<user>@<server>' text will not be shown. Instead, the session name will be shown mysession. mysession> Configuration Mode: If configuration mode is entered, the final prompt character will change from '>' to '#'. Version Page 34

35 Default session: Named session: mysession# If the configuration mode context node is changed, then the new datastore target object name will be shown as well: mysession# interfaces mysession(interfaces)# interface eth0 mysession(interface)# Continuation Mode: If a backslash, end-of-line sequence ended the previous line, the prompt will simply be the word 'more' indented 3 spaces: andy@myserver> get \ more> The 'more>' prompt will continue if the new line also ends in with an escaped end-of-line. When a new line is finally terminated, all the fragments are spliced together and delivered as one command line. Note: context-sensitive command completion is not available in this mode. Choice mode: If a partial command has been entered in interactive mode, and the script interpreter needs to prompt for a YANG 'choice' parameter, then a list of numbered cases will be presented, and the prompt will be the same as it was before (depending on whether a NETCONF session is active or not), except a colon character (':'), followed by the command name, will be added at the end. As long as parameters for the same command are being entered (i.e., prompted for child nodes within a selected case, the command name will be appended to the prompt. Version Page 35

36 sget Enter a number of the selected case statement: 1: case varref: leaf varref 2: case from-cli: leaf target leaf optional anyxml value Enter choice number [1-2]: andy@myserver:sget> Parameter mode: If a partial command has been entered in interactive mode, and the script interpreter needs to prompt for a leaf or leaf-list, then the parameter name will appear in angle brackets ('<' and '>'). Filling mandatory case /sget/input/from/from-cli: Enter string value for leaf <target> andy@myserver:sget> If the 'ncx:password' extension is part of the YANG definition for the leaf or leaf-list, then the characters entered at the prompt in this mode will not be echoed, and they will not be saved in the command history buffer. Any default value will not be printed either. Instead, 4 asterisks '****' will be printed, even though the correct value will be used in the command. If a default value is available, it will appear in square brackets ('[' and ']'). In this case, entering 'return' will not be interpreted as an empty string, but rather the default value that was presented. > connect Enter string value for leaf <user> [andy] :connect> Enter string value for leaf <server> [myserver] :connect> Enter string value for leaf <password> [****] :connect> Enter uint16 value for leaf <port> [830] :connect> Enter uint32 value for leaf <timeout> [30] [connect sequence text printed, and then prompt changes...) andy@myserver> Version Page 36

37 Note: After a NETCONF session is terminated for any reason, the connection parameters will be remembered, and presented as defaults the next time the connect command is entered. False Conditional Block Mode If a conditional command (if, elif, else, or while command) is active, but the conditional expression is false, then any commands defined within that conditional block will not be executed. If this occurs in interactive mode instead of a script, the string '[F]' will be added to the command prompt. Note that the 'help' and 'log-info' commands do not get executed in the following example: > if 0 [F]> help [F]> log-info 'this will not get printed' [F]> end > Command Name The command name can be entered with or without an XML prefix: session1> nc:get session1> get If there is a prefix (e.g., 'nc:get'), then it needs to be one of the XML prefixes in use at the time. Use the 'show modules' command to see the modules and prefixes in use. The YANG prefix will usually be the same as the XML prefix, but not always. XML prefixes are required to be unique, so if any 2 YANG modules pick the same prefix, then 1 of them has to be changed for XML encoding purposes. If the --default-module configuration parameter (or $$default-module system variable) is set, it will be used to resolve a command name without any prefix, if it is not a NETCONF or yangcli-pro command. An error message will be printed if the command entered cannot be found in any YANG module, or if there are multiple commands that match the same string ncx:default-parm Extension Version Page 37

38 Each command may define a default parameter, by placing an 'ncx:default-parm' extension in the rpc input section in the YANG rpc statement. This extension allows less typing in yangcli-pro to accomplish the same thing. If the script interpreter encounters a string in the command line that is not a recognized parameter for that command, and there is a default parameter defined, then the string will be used as a value for the default parameter. For example, the 'show' parameter is the default parameter for the 'history' command, so both of these commands will be interpreted to mean the same thing: > history --show=10 > history 10 Note: the default parameter does not allow the wrong form of a parameter type to be entered, to accept the default for that parameter. For example, the 'show' parameter above has a default value of '25': # this is the same as history show=25 > history # this is an error, not the same as the above > history show The following table shows most of the default parameters that are available. If a command has only 1 parameter then it is made the default parameter automatically. Default Parameters command action alias aliases cd connect create elif else if eventlog fill help history target var show dir server target expr expr expr show target command show default parameter Version Page 38

39 command insert load log-debug log-error log-info log-warn merge mgrload recall replace run set-log-level sget sget-config xget xget-config while target module msg msg msg msg target module index target script log-level target target select select expr default parameter Parameter Mode Escape Commands There are 4 escape sequence commands that can be used while entering parameters. They all begin with the question mark character ('?'), and end with the 'Enter' key. Control key sequences are not used because that would interfere with command line editing keys. Parameter mode escape sequences escape sequence description? Print some help text?? Get all available help text?s Skip this parameter?se Skip to the end of the current parameter set?c Cancel this command Note: If the current parameter is considered hidden (ncx:hidden extension used in the YANG definition), then no help will be available for the parameter, even though it is accessible. This also apples to the help command. Any command or parameter designated as ncx:hidden will be treated as an unknown identifier, and no help will be given. Note: Skipping mandatory nodes with the '?s' command is affected by the --bad-data configuration parameter and $ $bad-data system variable. An error, warning, or confirmation check may occur. Refer to the CLI Reference for more details. Version Page 39

40 The '?s' command to skip a parameter will allow the current command to be skipped, even if it is a mandatory parameter. The '?se' command will allow the current command to be skipped, even if it is a mandatory parameter. The rest of the parameters in the same sibling set will also be skipped, but only if they are optional parameters. This mode is only active if the optional parameter is used in the command that is causing parameters to be entered, or the $$optional global variable is set to 'true'. The sibling set is defined as the nodes in the parent containment node (case, list, or container). Note: If there are any YANG defined values (e.g., enumeration, bits, default-stmt) available for the current parameter, then pressing the tab key will list the full or partial completions available Using Inline XML or JSON Data It is possible to assign JSON or XML encoded data to a variable or command parameter. This can be done at the command prompt or within a script. A special string consisting of 3 double quotes is used to indicate the beginning or end of the inline data. The syntax is simple: <start-tag> [wsp] <XML element -or- JSON object> [wsp] <end-tag> Example <edit-config> command setting the <config> container to an XML value: sesa> edit-config target=candidate config="""<config><int8.1>5</int8.1></config>""" The end-of-line continuation marker '\' is not needed when entering inline data. The data may appear or multiple lines. Example script using JSON: edit-config target=candidate config=""" {"config": { "container.1" : { "uint16.1" : 42, "uint32.1" : 4200, "int32.1" : """ Example script using XML: Version Page 40

41 edit-config target=candidate config=""" <config> <container.1> <uint16.1>42</uint16.1> <uint32.1>4200</uint32.1> <int32.1>-4200</int32.1> </container.1> </config> """ When entering inline data at the command line, the more> command prompt mode will be entered automatically if an odd number of tags are found on the input line. When assigning inline data to a variable, there is no object specified, so the YANG anydata type is used. In this case any valid XML element or JSON object can be assigned. Example Variable Assignment andy@localhost> $foo = """ more> <A> more> <leaf1>testing</leaf1> more> </A> more> """ OK andy@localhost> show var foo foo [/struct] A { leaf1 testing andy@localhost> andy@localhost> Restrictions: Only the following YANG data node types are supported: container list anyxml anydata input output Version Page 41

42 The maximum length of an input line, including all inline data, is bytes. If a JSON array is entered instead of a JSON object, then only the first instance will be used. Any additional instances will be ignored Using XPath Expressions There are some command parameters, such as the --target parameter for the create command, that accept XPath absolute path expressions. If prefixes are present, then they must match the set of XML prefixes in use at the time. Use the show modules command to see the current set of prefixes. If prefixes are not used, then the first available matching XML namespace will be used instead. If the starting forward slash character ('/') is missing, then it will be added. # these are all the same value (entered in 'fill' command) :fill> system :fill> /system :fill> /sys:system It is important to remember 2 simple rules to avoid common errors in XPath expressions: 1. String constants must be quoted with single quote characters. The expression [name=fred] is not the same as [foo='fred']. The former compares the 'name' node value to the 'fred' node value. The latter compares the 'name' node value to the string 'fred'. 2. The double quote character (' ') is not allowed in XPath --select parameter expressions because the expression will be sent to the server inside a double-quoted string. If an incomplete XPath absolute path expression is entered, and the script interpreter is in interactive mode, then the user will be prompted to fill in any missing mandatory nodes or key leafs. # complete form of ifmtu leaf :fill> /interfaces/interface[name='eth0']/ifmtu # incomplete form of ifmtu leaf :fill> /interfaces/interface/ifmtu Filling key leaf <name>: Enter string value: The --select parameter for the xget and xget-config commands accepts full XPath expressions. The expression must yield a node-set result in order to be used as a filter in NETCONF get and get-config operations. One of the simplest XPath filters to use is the descendant-or-self filter ('//<expr>'). For example, this command will retrieve all instances of the 'ifmtu' leaf: Version Page 42

43 xget //ifmtu When interface (or any list) entries are returned by netconfd-pro, they will contain the the entire path back to the root of the YANG module, not just the specified node. Also, any key leafs within a list are added. This is only done if the XPath expression is missing any predicates for key leafs. This is different than XPath 1.0 as used in XSLT. Since NETCONF get and get-config operations return complete XML instance documents, not node-sets, the ancestor nodes and naming nodes need to be added. # reply shown with --display-mode=plain data { interfaces { interface eth0 { name eth0 ifmtu 1500 interface eth1 { name eth1 ifmtu Special Parameter Handling Some special handling of YANG data structures is done by the script interpreter. Containers Some parameters, such as the --source and --target parameters in many commands, are actually represented as a container with a single child -- a choice of several leaf nodes. In this situation, just the name of the desired leaf node can be entered (when in idle mode), as the 'contents' of the container parameter. andy@myserver> sget-config /system source=candidate Choices and Cases If a parameter name exact-match is not found, and a partial match is attempted, then choice and case node names will be ignored, and not cause a match. Since these nodes never appear in the XML PDUs they are treated as transparent nodes (wrt/ parameter searches) unless they are specified with their full name. Version Page 43

44 Parameters that are a choice of several nodes, similar to above, except without a parent container node, (e.g., --helpmode) can be omitted. The accessible child nodes within the case nodes can be entered directly (e.g., sget --target parameter). # this is not allowed because 'help-mode' is not complete > help --command=help --help-mo=brief # this is allowed because 'help-mode' is complete, # even though help-mode is a choice and 'brief' is # an empty leaf > help help help-mode=brief # choice and case names are transparent when # searching for parameter names, so the # following command is the same as above > help help brief Lists and Leaf-Lists When filling a data structure and a descendant node is entered, which is a YANG list or leaf-list, then multiple entries can be entered. After the node is filled in, there will be a prompt (Y/N, default no) to add more list or leaf-list entries. Binary Data Type The YANG binary data type is supported. Parameters of this type should be entered in plain text and they will be converted to binary format Command Completion The 'tab' key is used for context-sensitive command completion: If no command has been started, a list of available commands is printed If a partial command is entered, a list of commands which match the characters entered so far is printed If a command is entered, but no parameters, then a list of available parameters is printed If a command is entered, and the cursor is within a command name, then a list of parameters which match the characters entered so far is printed If a command is entered, and the cursor is after a command name, but not within a value string, then a list of available parameters is printed If a command is entered, and the cursor is within a command value, then a list of possible values which match the characters entered so far is printed. Note that not all data types support value completion at this time. If no values are available, but a default value is known, that value will be printed If a session is active, and whitespace followed by the forward slash '/' character is entered, a list of top-level data node names is printed. Once a top-level name and a trailing slash '/' character is entered, pressing the tab key again will print the names of the child nodes of the current data node. Only schema-node strings are supported at this time. Auto-completion will not work if predicates are present in the absolute path expression. Version Page 44

45 Command list example: no NETCONF session is active: YumaPro yangcli-pro Manual > <hit tab key> cd fill history mgrload quit run connect help list pwd recall show Command list example: NETCONF session is active <hit tab key> cd get-schema recall close-session help replace commit history restart connect insert run copy-config kill-session save create list sget create-subscription load delete load-config show delete-config lock shutdown discard-changes merge unlock edit-config mgrload validate fill no-op xget sget-config get pwd xget-config get-config quit Command Line Editing The command line parser is based on libtecla, a freely available library. The home page is located here: The complete user guide for configuring libtecla is located here: If the file $HOME/.teclarc exists, then libtecla will use it to configure the key bindings. By default, libtecla uses emacs key bindings. There is no need for any further libtecla configuration if emacs mode is desired. In order to use the vi editor key bindings, the $HOME/.teclarc file must exist, and it must contain the following line: edit-mode vi Version Page 45

46 Custom key bindings are also available. Refer to the libtecla documentation for more details on command line editing key customization. The control key sequence (^F == control key and f key at the same time). The letter is not case-sensitive, so ^F and ^f are the same command. The alt key sequence (M-f == alt key and f key at the same time). The letter is not case-sensitive, so M-F and M-f are the same command. The following table shows the the most common default key bindings: Common editing key bindings command ^C ^F ^B ^A ^E ^U M-f M-b ^P ^N clear screen cursor right cursor-left beginning of line end of line delete line forward-word backward word up history down history description Command History Each command line is saved in the command history buffer, unless a password is being entered in parameter mode. By default, the previous history line (if any) will be shown if the ^P key is pressed. By default, the next history line (if any) will be shown if the ^N key is pressed. In addition, the history command can be used to control the command line buffer further. This command has 4 submodes: show: show maximum of N history entries (default is 25) clear: clear the history buffer save: save the history buffer to a file load: load the history buffer from a file By default, the command line history buffer is loaded when the program starts, and saved when the program exits. This behavior can be turned off by setting the --autohistory configuration parameter to 'false'. The '!' character is special when editing commands. If the first character is '!', and it is followed by a number or a non-zero character, the line will be interpreted as a recall request: Version Page 46

47 >!42 == recall command number 42 (same as recall 42) >!get == recall the most recent command line starting with 'get' Refer to the Command Reference section for more details on the history command Command Responses The command output and debugging messages within yangcli-pro is controlled by the current log level (error, warn, info, debug, debug2, debug3). If a command is executed by the script interpreter, then a response will be printed, depending on the log level value. If the log level is 'info' or higher, and there were no errors and no response, then the string 'OK' is printed. > $foo = 7 OK > If the log-level is set to 'error' or 'warn', then the 'OK' messages will be suppressed. If the log level is set to 'debug' or higher, then responses from the server will be echoed to the log stream (STDOUT, log file and/or syslog). The current display mode will be used when printing data structures such as <rpc-error> and <notification> element contents. If an error response is received from the server, it will always be printed to the log. andy@myserver> create /system Filling container /system: RPC Error Reply 5 for session 8: rpc-reply { rpc-error { error-type application error-tag access-denied error-severity error error-app-tag limit-reached error-path /nc:rpc/nc:edit-config/nc:config/sys:system error-message 'max-access exceeded' andy@myserver> Refer to the --log-level parameter in the CLI Reference for more details. Logging capabilities are also discussed in more detail in the YumaPro User Manual. Version Page 47

48 2.3 Controlling Terminal Output YumaPro yangcli-pro Manual The yangcli-pro and yp-shell programs support terminal output filtering and paginated output. Pipe commands allow the line-by-line terminal output to be filtered, formatted, or redirected. Pipe Commands: filter show command output and server response output Pagination: pause output after each page, allowing the user to continue or quit the output Display Mode: Specifies the display format (e.g., plain, XML, JSON) Pipe Commands Pipe commands are used to control the terminal output Pipe Commands: filter show command output and server response output begin: start output after this pattern matches include: include lines that match this pattern exclude: exclude lines that match this pattern redirect: send output to a text file instead of the screen display: format the output in XML or JSON Usage Notes: The pipe commands can be combined. The include and exclude commands can be specified multiple times The redirect filespec is relative to the current working directory The display parameter is used to over-ride the current $$display-mode variable setting. Examples: The show fan command is an external command from the example-show.yang module. It is not a real command within yangcli-pro. The full output of the command is shown first, without any pipe commands: > show fan 1 --full Report for Fan 1 put fan status here... put more fan status here... put even more fan status here... The begin command: this is case-sensitive so the first fan matches, not Fan > show fan 1 --full begin fan Version Page 48

49 put fan status here... put more fan status here... put even more fan status here... YumaPro yangcli-pro Manual > The include command: > show fan 1 --full include more put more fan status here... put even more fan status here > The exclude command: > show fan 1 --full exclude more Report for Fan 1 put fan status here... > The display command: andy@localhost> sget /system/uname display json Filling container /system/uname: RPC Data Reply 11 for session 3 [default]: { "yuma-netconf:rpc-reply": { "yuma-netconf:data": { "yuma-system:system": { "uname": { "sysname":"linux", "release":" generic", "version":"#127-ubuntu SMP Mon Dec 11 12:16:42 UTC 2017", "machine":"x86_64", "nodename":"andy-2i7" andy@localhost> The display and redirect commands combined: andy@localhost> sget /system redirect ~/test1.json display json Version Page 49

50 Filling container /system: YANG Definition container pipe { ncx:abstract; ncx:hidden; description "Pipe command sub-commands. The 'begin', 'include', and 'exclude' parameters are used to filter command output. If these parameters contain any pattern meta-characters, then they will be treated as a YANG pattern string. If a plain string is found instead, then this string must be found in the line to be considered a match. Each output line is processed in the following manner: 1) if begin set and not triggered yet, then test the line. If a match then disable this step for future lines and continue testing output, else skip this line. 2) check each exclude parameter. If any match then skip this line. 3) check each include parameter. If any match then include this line, else skip this line. 4) include the line in the output. If the 'redirect' parameter is present then the filtered output will be sent to a file instead of the session. If the 'display'parameter is present then the specifed display format will be used for the output and the filtering format. By default, the current display-mode is used for both filtering and output formats."; leaf begin { type string; description "Specifies the pipe begin line pattern."; leaf-list include { type string; description "Specifies a pipe include line pattern. Multiple parameters are treated as a logical-or expression."; leaf-list exclude { type string; description "Specifies a pipe exclude line pattern. Multiple parameters are treated as a logical-or expression."; leaf redirect { Version Page 50

51 YumaPro yangcli-pro Manual type string; description "Specifies the pipe output redirect filespec. If this filespec already exists then output will be appended to the file."; leaf display { type enumeration { enum xml { description "Display output in XML"; enum json { description "Display output in JSON"; enum curmode { description "Display output is the current $$display-mode"; default "curmode"; description "Specifies the pipe output display format."; Pagination Pagination: pause output after each page, allowing the user to continue or quit the output --More-- prompt displayed at each pause terminal length command controls number of lines printed per page $$term-length variable also controls number of lines printed per page space bar prints next page, return prints next line, q to quit output leaf term-length { description "Specifies the length of the terminal to use for page mode output with the -More- prompt. This parameter is ignored in batch mode. It is only used if the output session is operating in interactive mode. If the value 0 is used then the 'More' prompt will be disabled. Otherwise this value represents the number of lines to output for each screen in pagination output mode."; type uint16 { range " "; default 0; Version Page 51

52 Example using pagination and pipe commands together: term length 10 OK sget /system/uname display json Filling container /system/uname: RPC Data Reply 12 for session 3 [default]: { "yuma-netconf:rpc-reply": { "yuma-netconf:data": { "yuma-system:system": { "uname": { "sysname":"linux", "release":" generic", "version":"#127-ubuntu SMP Mon Dec 11 12:16:42 UTC 2017", --More-- Examples setting terminal length: > $$term-length = 20 > term length Display Mode The display mode controls the output format used to display YANG data: Not all commands use YANG data so the display mode does not affect all commands. Some show commands for example use plain text output only. Commands that return OK or some error message are not affected by the display mode. Commands that return server data and display the response support all display modes Setting the Display Mode: $$display-mode variable controls the output display format The pipe command display overrides the $$display-mode setting for the current command Displaying the current display mode: > show var display-mode display-mode cli YANG Definition: Version Page 52

53 leaf display-mode { description "Controls how values are displayed during output to STDOUT or a log file."; type enumeration { enum plain { description "Plain identifier without any prefix format."; enum prefix { description "Plain text with XML prefix added format."; enum module { description "Plain text with module name as prefix added format."; enum xml { description "XML format."; enum xml-nons { description "XML format, but no namespace (xmlns) attributes will be generated."; enum json { description "JSON format."; enum cli { description "CLI format."; default plain; Plain Mode Example: andy@localhost> sget /system/uname Filling container /system/uname: RPC Data Reply 14 for session 3 [default]: rpc-reply { data { system { uname { sysname Linux release generic version '#127-Ubuntu SMP Mon Dec 11 12:16:42 UTC 2017' machine x86_64 nodename andy-2i7 Version Page 53

54 CLI Mode example: sget /system/uname Filling container /system/uname: RPC Data Reply 15 for session 3 [default]: rpc-reply data system uname sysname Linux release generic version '#127-Ubuntu SMP Mon Dec 11 12:16:42 UTC 2017' machine x86_64 nodename andy-2i7 andy@localhost> 2.4 NETCONF Device Configuration The yangcli-pro program can be configured to associate a name with a set of device parameters to start a NETCONF device with a server. These named devices are saved in a configuration file. Use the --autodevices to suppress automatic loading of this file. The default is to load this file at start-up and save it upon exit. By default, the devices configuration is saved in $HOME/.yumapro/yangcli_pro_devices.conf. To override this file, set --autodevices=false and use the devices-cfg command to load a specific devices configuration file Saving Devices To save a device, the text configuration file can be edited or the 'device-cfg save' command can be used. > connect device=andy server=myserver password=mypassword. startup screeen. andy@myserver> device-cfg save device-a Saved current device as 'device-a' andy@myserver> Multiple Devices Version Page 54

55 Multiple devices can be active at once, however only one command at a time can be sent. This will be improved in a future release. Just use the start-session command to start a different session. Only one instance of each named session with its device can be active at the same time Saving the Configured Devices The device configuration can be saved or loaded at run-time, even if the --autodevices=true parameter is used (the default). The devices-cfg command is used to load and save this file. session-a> devices-cfg save Saved 2 sessions OK to '~/.yumapro/yangcli_pro_devices.conf' session-a> To save the devices to a different file, simply provide the filespec in the 'devices-cfg save' command: session-a> devices-cfg save myusers.conf Saved 2 devices OK to 'mydevices.conf' session-a> Loading Additional Configured Devices Additional devices can be added to the configuration in memory with the 'devices-cfg load' command. The named devices in the file cannot conflict with names already in use or the duplicate devices will be skipped. session-a> devices-cfg load devices.conf Loaded 3 sessions OK from 'devices.conf' session-a> Displaying the Configured Devices The devices that are available can be displayed with the 'devices-cfg show' command. The --brief and --full extensions are available for this command. Version Page 55

56 session-a> devices-cfg show Saved devices source: '~/.yumapro/.yangcli_pro_devices.conf' Device 'desktop': server: connected: false Device 'device-a': server: localhost connected: false Device 'device-b': server: connected: false Displaying Devices Displaying a Specific Device To see information about a specific device, use the 'device-cfg show' command: > device-cfg show device-a Device 'device-a': server: localhost connected: false Saved Device Configuration File Format The saved sessions are stored in a YumaPro configuration file. The file contents must conform to the following YANG container definition: container saved-devices { ncx:abstract; description "Represents all the saved devices in the ~/.yumapro/yangcli_pro_devices file. Use the 'devices' command to access this file. Edit by hand only if you follow this YANG definition."; list device { description "The list of devices to use during this test-suite."; key name; leaf name { type nt:ncxname; description Version Page 56

57 "The name of the saved device. The 'device save' command will use the string as the default."; leaf devicetype { type string; description "Device type for NETCONF devices."; leaf server { type inet:host; mandatory true; description "IP address or DNS name of the NETCONF server target."; leaf ncport { type uint16 { range "1..max"; default 830; description "NETCONF port number to use. If not present, then port 830, followed by port 22, will be tried."; uses ncxapp:protocolsparm; Device Configuration File Example The following example file shows a valid session configuration file: saved-devices { device 'desktop' { server ' ' ncport 830 protocols "netconf1.0 netconf1.1" device 'device-a' { server 'localhost' ncport 830 protocols "netconf1.0 netconf1.1" device 'device-b' { server ' ' ncport 830 protocols "netconf1.1" 2.5 NETCONF User Configuration Version Page 57

58 The yangcli-pro program can be configured to associate a name with a set of user parameters to start a NETCONF user with a server. These named users are saved in a configuration file. Use the --autousers to suppress automatic loading of this file. The default is to load this file at start-up and save it upon exit. By default, the users configuration is saved in $HOME/.yumapro/yangcli_pro_users.conf. To override this file, set --autousers=false and use the users-cfg command to load a specific users configuration file Creating New Users To create a new user, use the 'user-cfg create' command. > user-cfg create=usr1 user-name=admin password=fredlow A new user is created: user-id=usr1 name=admin password=fredlow > user-cfg show usr1 User 'usr1': user: admin password: fredlow connected: false > Saving Users To save a user, the text configuration file can be edited or the 'user-cfg save' command can be used. > connect user=andy server=myserver password=mypassword. startup screeen. andy@myserver> user-cfg save user-a Saved current user as 'user-a' andy@myserver> Multiple Users Multiple users can be active at once, however only one command at a time can be sent. This will be improved in a future release. Just use the start-session command to start a different session. Only one instance of each named session with its user can be active at the same time Saving the Configured Users The use configuration can be saved or loaded at run-time, even if the --autousers=true parameter is used (the default). The rusers-cfg command is used to load and save this file. Version Page 58

59 session-a> users-cfg save Saved 2 sessions OK to '~/.yumapro/yangcli_pro_users.conf' session-a> To save the sessions to a different file, simply provide the filespec in the 'users-cfg save' command: session-a> users-cfg save myusers.conf Saved 2 users OK to 'myusers.conf' session-a> Loading Additional Configured Users Additional users can be added to the configuration in memory with the 'users-cfg load' command. The named users in the file cannot conflict with names already in use or the duplicate users will be skipped. session-a> users-cfg load users.conf Loaded 3 sessions OK from 'users.conf Displaying the Configured Users The users that are available can be displayed with the 'users-cfg show' command. The --brief and --full extensions are available for this command. session-a> users-cfg show Saved users source: '~/.yumapro/.yangcli_pro_users.conf' User 'usera': user: usernamea password: password A connected: false User 'userb': user: usernameb password: password B connected: false User 'userc': Version Page 59

60 user: usernamec password: password C connected: false Displaying Users Displaying a Specific User To see information about a specific user, use the 'user-cfg show' command: > user-cfg show usera User 'usera': user: usernamea password: password A connected: false Saved User Configuration File Format The saved sessions are stored in a YumaPro configuration file. The file contents must conform to the following YANG container definition: container saved-users { ncx:abstract; description "Represents all the saved users in the ~/.yumapro/yangcli_pro_users file. Use the 'users' command to access this file. Edit by hand only if you follow this YANG definition."; list userid { description "The list of users to use."; key name; leaf name { type nt:ncxname; description "The id of the saved user."; leaf user { type nt:ncxname; mandatory true; description "The user name of the session."; choice pass { mandatory true; Version Page 60

61 leaf password { type string; ncx:password; description "User password to use for NETCONF users. If none, then user will be prompted before connecting."; leaf no-password { type empty; uses SshKeyParms; uses SslKeyParms; User Configuration File Example The following example file shows a valid session configuration file: saved-users { userid 'usera' { user 'usernamea' password 'passworda' public-key '$HOME/.ssh/id_rsa.pub' private-key '$HOME/.ssh/id_rsa' ssl-fallback-ok true ssl-trust-store '$HOME/.ssl/trust-store.pem' ssl-key '$HOME/.ssl/yangapi-client.key' ssl-certificate '$HOME/.ssl/yangapi-client.crt' userid 'userb' { user 'usernameb' password 'passwordb' public-key '$HOME/.ssh/id_rsa.pub' private-key '$HOME/.ssh/id_rsa' ssl-fallback-ok true ssl-trust-store '$HOME/.ssl/trust-store.pem' ssl-key '$HOME/.ssl/yangapi-client.key' ssl-certificate '$HOME/.ssl/yangapi-client.crt' 2.6 NETCONF Session Configuration The yangcli-pro program can be configured to associate a name with a set of session parameters to start a NETCONF session with a server. These named sessions are saved in a configuration file. Use the --autosessions to suppress automatic loading of this file. The default is to load this file at start-up and save it upon exit. By default, the sessions configuration is saved in $HOME/.yumapro/yangcli_pro_sessions.conf. To override this file, set --autosessions=false and use the sessions-cfg command to load a specific sessions configuration file. The start-session command is used to start a named session: > start-session session-a Version Page 61

62 . startup screeen. session-a> Saving Sessions To save a session, the text configuration file can be edited or the 'session-cfg save' command can be used. > connect user=andy server=myserver password=mypassword. startup screeen. andy@myserver> session-cfg save session-a Saved current session as 'session-a' andy@myserver> Multiple Sessions Multiple sessions can be active at once, however only one command at a time can be sent. This will be improved in a future release. Just use the start-session command to start a different session. Only one instance of each named session can be active at the same time. > start-session session-a. startup screeen. session-a> start-session session-b. startup screeen. session-b> Note that when a session is started, the active session is set to that session Changing the Active Session To change the active session and issue commands to a different server, use the 'session set-current' command. This command will cause all subsequent remote commands to be sent to the server associated with the named session. Version Page 62

63 session-a> session set-current session-b session-b> Since the set-current parameter is the default parameter, this command can be simplified: session-a> session session-b session-b> To switch to the default session, use the session name default. If the default session is connected, then the user and host name will be shown. If not, a simple '>' prompt will be shown instead. session-a> session default andy@myserver> Saving the Configured Sessions The session configuration can be saved or loaded at run-time, even if the --autosessions=true parameter is used (the default). The sessions-cfg command is used to load and save this file. session-a> sessions-cfg save Saved 2 sessions OK to '~/.yumapro/yangcli_pro_sessions.conf' session-a> To save the sessions to a different file, simply provide the filespec in the 'sessions-cfg save' command: session-a> sessions-cfg save mysessions.conf Saved 2 sessions OK to 'mysessions.conf' session-a> Loading Additional Configured Sessions Version Page 63

64 Additional sessions canbe added to the configuration in memory with the 'sessions-cfg load' command. The named sessions in the file cannot conflict with names already in use or the duplicate session will be skipped. session-a> sessions-cfg load sessions.conf Loaded 3 sessions OK from 'sessions.conf' session-a> Displaying the Configured Sessions The sessions that are available can be displayed with the 'sessions-cfg show' command. The --brief and --full extensions are available for this command. session-a> sessions-cfg show Saved sessions source: 'mysessions.conf' Session 'session-a': user: andy server: localhost connected: true Session 'session-b': user: andy server: eval.yumaworks.com connected: false Displaying Sessions Displaying the Active Session To see information about the active session, use the 'session-cfg' command session-a> session-cfg Session 'session-a': user: andy server: localhost connected: true Session 'session-b': user: andy server: eval.yumaworks.com Version Page 64

65 connected: false Displaying a Specific Session To see information about a specific session, use the 'session-cfg show' command: session-a> session-cfg show session-b Session 'session-b': user: andy server: eval.yumaworks.com connected: false session-a> Terminating a Named Session The stop-session command is used to terminate a specific session. The <close-session> command will be sent on the specified session and the connection gracefully terminated. session-a> stop-session session-b session-a> The active session can also be terminated although no new session will be selected automatically: session-a> stop-session session-a > Saved Session Configuration File Format The saved sessions are stored in a YumaPro configuration file. The file contents must conform to the following YANG container definition: container saved-sessions { description "Represents all the saved sessions in the ~/.yumapro/yangcli_pro_sessions file. Use the 'sessions' command to access this file. Version Page 65

66 Edit by hand only if you follow this YANG definition."; list session { description "The list of sessions to use during this test-suite."; key name; leaf name { type nt:ncxname; description "The name of the saved session. The 'session save' command will use the string <user>@<server-address> as the default."; leaf user { type nt:ncxname; mandatory true; description "The use name of the session."; leaf password { type string; ncx:password; description "User password to use for NETCONF sessions. If none, then user will be prompted before connecting."; uses SshKeyParms; leaf server { type inet:host; mandatory true; description "IP address or DNS name of the NETCONF server target."; leaf ncport { type uint16 { range "1..max"; default 830; description "NETCONF port number to use. If not present, then port 830, followed by port 22, will be tried."; uses ncxapp:protocolsparm; container start-commands { ywx:cli-text-block; description "An optional block of yangcli commands to run after the session is successfully started."; Version Page 66

67 Session Configuration File Example The following example file shows a valid session configuration file: saved-sessions { session session-a { user andy password mypassword public-key $HOME/.ssh/id_rsa.pub private-key $HOME/.ssh/id_rsa server localhost ncport 830 protocols "netconf1.0 netconf1.1" session session-b { user andy password mypassword public-key $HOME/.ssh/id_rsa.pub private-key $HOME/.ssh/id_rsa server localhost ncport 830 protocols "netconf1.0 netconf1.1" session A { user andy2 password newpassword public-key $HOME/.ssh/id_rsa.pub private-key $HOME/.ssh/id_rsa server localhost ncport 830 protocols "netconf1.0 netconf1.1" Version Page 67

68 2.7 NETCONF Group Configuration The yangcli-pro program can be configured to manage the session groups. It associates a group name with a set of sessions to start NETCONF sessions with servers. A group name is not allowed to have the same name as any session name. This allows the 'session set-current' command to select a group or an individual session. The named groups and their sessions are saved in a configuration file. Use the --autosessions to automatic loading of this file. The default is to load this file at start-up and save it upon exit. suppress By default, the group configuration is saved in $HOME/.yumapro/yangcli_pro_sessions.conf. To override this file, set --autosessions=false and use the sessions-cfg command to load a specific sessions configuration file Create group The group command is used to create a group. The 'session' parameter must also be present. Example of 'group create': > group create=ab session=session-a session=session-b > > group create=a1a2a3 session=a1 session=a2 session=a List group The group list command is used to list the names of all the groups > group list Group 'AB' This group is not connected. missing-ok: false missing-connect-ok: false lost-ok: false reconnect-interval: 30 reconnect-tries: 5 connected_cnt: 0 number_of_sessions: 2 Session 'session-a' connected:false Session 'session-b' connected:false Group 'a1a2a3' This group is not connected. missing-ok: false missing-connect-ok: false lost-ok: false reconnect-interval: 30 reconnect-tries: 5 connected_cnt: 0 number_of_sessions: 3 Session 'a1' connected:false Session 'a2' connected:false Session 'a3' connected:false < Version Page 68

69 2.7.3 Delete group The group delete command is used to delete a group. > group delete=ab > > group delete=a1a2a3 > > group list No groups found > Add group The group add command is used to add sessions to a named group. The 'session' parameter must also be present. > group add=ab session=session-b > > group list Group 'AB' This group is not connected. missing-ok: false missing-connect-ok: false lost-ok: false reconnect-interval: 30 reconnect-tries: 5 connected_cnt: 0 number_of_sessions: 2 Session 'session-a' connected:false Session 'session-b' connected:false Remove Group The group remove command is used to remove the sessions from a name group. The 'session' parameer must also be present. > group remove=ab session=session-a > > group list Group 'AB' This group is not connected. missing-ok: false missing-connect-ok: false lost-ok: false reconnect-interval: 30 reconnect-tries: 5 connected_cnt: 0 number_of_sessions: 1 Session 'session-b' connected:false Show Group The group show command is used to show the name of the group to show. Example of 'group show' Version Page 69

70 > group show=ab Group 'AB' This group is not connected. missing-ok: false missing-connect-ok: false lost-ok: false reconnect-interval: 30 reconnect-tries: 5 connected_cnt: 0 number_of_sessions: 1 Session 'session-b' connected:false > YumaPro yangcli-pro Manual Connect Group The group connect command is used to start a named group with session group parameters: lost-ok, missingconnect-ok, missing-ok, reconnect-interval, and reconnect-tries. The default parameters value are false. > group connect=ab yangcli-pro: Starting NETCONF session for andy on localhost over ssh on port 830 NETCONF session established for xxxxx on localhost. startup screeen. AB> Client Session Id: 1 Server Session Id: NETCONF session established for xxxxx on localhost. startup screeen. AB> Client Session Id: 2 Server Session Id: AB> group list Group 'AB' This group is fully connected. missing-ok: false missing-connect-ok: false lost-ok: false reconnect-interval: 30 reconnect-tries: 5 connected_cnt: 2 number_of_sessions: 2 Session 'session-a' connected:true Session 'session-b' connected:true Help Group Use command of help group to print all the group help text. Version Page 70

71 > help group group Manage the yangcli-pro session groups. A group name is not allowed to have the same name as any... input default parameter: session choice groupcmd <Mandatory> case connect leaf connect [NcxIdentifier] Connect to all sessions in the specified group. leaf missing-ok [boolean] [d:false] If truew, then it is OK to manage this group if 1 or more sessions identified in... leaf missing-connect-ok [boolean] [d:false] If true, then it is OK to manage this group if 1 or more sessions identified in... leaf lost-ok [boolean] [d:false] If true, then it is OK to manage this group if 1 or more sessions are lost after... leaf reconnect-tries [uint32] [d:5] Indicates the number of times yangcli will attempt to reconnect to a session if... leaf reconnect-interval [uint32] [d:10] Indicates the number of seconds yangcli will wait to re-establish a connection i... leaf create [NcxIdentifier] Name of the group to create. The 'session' parameter must also be present leaf delete [NcxIdentifier] Name of the group to delete leaf add [NcxIdentifier] Name of the group to add some sessions. The 'session' parameter must also be presen... leaf remove [NcxIdentifier] Name of the group to remove some sessions. The 'session' parameer must also be pres... leaf show [NcxIdentifier] Name of the group to show > leaf list [empty] List the names of all the groups saved-sessions { leaf-list session [NcxIdentifier] <Mandatory> Name of a session that is being added to the group Saving Groups To save a group, the text configuration file can be edited or the 'sessions-cfg save' command can be used. The session configuration can be saved or loaded at run-time, even if the --autosessions=true parameter is used (the default). The sessions-cfg command is used to load and save this file. Version Page 71

72 AB> sessions-cfg save session 'session-a' { user 'andy' password 'xxxxx' public-key '$HOME/.ssh/id_rsa.pub' private-key '$HOME/.ssh/id_rsa' server 'localhost' ncport 830 protocols "netconf1.0 netconf1.1" session 'session-b' { user 'andy' password 'xxxxx' public-key '$HOME/.ssh/id_rsa.pub' private-key '$HOME/.ssh/id_rsa' server 'localhost' ncport 830 protocols "netconf1.0 netconf1.1" group 'AB' { missing-connect-ok false missing-ok false lost-ok false reconnect-interval 30 reconnect-tries 5 session 'session-a' session 'session-b' Changing the Active group To change the active group and issue commands to a different server, use the 'session set-current' command. This command will cause all subsequent remote commands to be sent to the servers associated with the named group. a1a2a3> session set-current AB Group 'AB' is now active AB> 2.8 Using NETCONF Sessions The yangcli-pro program can be connected to up to 1000 NETCONF servers at a time. Use the connect or start-session command to start a NETCONF session. This section explains how to use yangcli-pro to manage a NETCONF server. By default, a NETCONF over SSH session will be started. Use the parameter transport=tls in the connect command to start a NETCONF over TLS session. Version Page 72

73 When a NETCONF session starts up, a <capability> exchange is done, and the server reports exactly what content it supports. This information is used extensively to customize the session, and report errors and warnings for the session Connection Startup Screen If the --log-level is set to 'info' or higher, then a startup screen will be displayed when a NETCONF session is started. It contains: startup banner client session ID server session ID protocol capabilities supported by the server Includes revision-date of supported module YANG modules supported by the server Includes any features and deviations supported in the module Enterprise specific capabilities supported by the server Default target database (<candidate> or <running>) Save operation mapping for the server with-defaults reporting capability reported by the server The following example shows a typical startup screen connecting to the netconfd-pro server: NETCONF session established for user on localhost Client Session Id: 1 Server Session Id: 1 Server Protocol Capabilities base:1.0 candidate:1.0 confirmed-commit:1.0 rollback-on-error:1.0 validate:1.0 url:1.0 xpath:1.0 notification:1.0 interleave:1.0 partial-lock:1.0 with-defaults:1.0 base:1.1 validate:1.1 confirmed-commit:1.1 yang-library:1.0 Server Module Capabilities ietf-netconf@ ietf-inet-types@ ietf-netconf-acm@ ietf-netconf-monitoring@ Version Page 73

74 YumaPro yangcli-pro Manual Server Enterprise Capabilities urn:yumaworks:params:xml:ns:netconf:config-id?id=7865 Protocol version set to: RFC 6241 (base:1.1) Default target set to: <candidate> Save operation mapped to: commit Default with-defaults behavior: explicit Additional with-defaults behavior: trim,report-all,report-all-tagged Yang-Library set to: RFC 7895 module-set-id: Server Tailored Context While a NETCONF session is active, the set of available YANG modules will be set to the modules that the server is using, if the --autoload configuration parameter is enabled. If the schema-retrieval capability is also available on the server, then the <get-schema> operation will be attempted for any YANG module specified in the <hello> message capabilities, but not available to the yangcli-pro program. When the server module capabilities are analyzed by the yangcli-pro client, the entire YANG module search path is checked for the specific module advertised in the capability. All the modules are partially parsed to check the actual namespace and revision date values. The following fields must exactly match in order for yangcli-pro to use a local YANG module, if --autoload=true. module name module revision date (if any) module namespace If the namespace URI value is different, it indicates that there is either a bug in one of the conflicting YANG modules, or that two different naming authorities picked the same module name. In this case, a warning will be generated during session initialization. Version Page 74

75 Any data returned from the server for YANG modules not currently available will be treated as a YANG 'anyxml' node, instead of the (unknown) YANG data type. If the module contains YANG features that are not advertised in the <capabilities> exchange, then those data definitions will not be available (by default) for use in yangcli-pro commands. If the module contains an object with a 'when' statement, and the 'when' XPath expression evaluates to 'false', then that data definition will not be available (by default) for use in yangcli-pro commands. The help command will be tailored to the modules, capabilities, features, and module deviations reported by the server in <capability> exchange. If autoload-get is true, the <sget /netconf-state/schemas> operation will retrieve the /netconf-state/schemas sub-tree and the YANG sub-modules not known to yangcli-pro will be loaded correctly. If autoload-get is false, then just the <hello> message module list will be used to retrieve YANG modules. If autoload-cache is true, the YANG modules that are retrieved with the <sget /netconf-state/schemas> operation will be cached. And cached module can be used by yangcli-pro. If autoload-save-cache is true, the modules held in the YANG module cache are saved when yangcli-pro exits. If autoload-save-cache is false, then the YANG modules that are cached will be not saved when yangcli-pro exit Retrieving Data There are 6 commands available to retrieve generic data (i.e., an arbitrary subset of an entire NETCONF database): command get get-config sget sget-config xget xget-config description raw NETCONF <get> operation raw NETCONF <get-config> operation high-level subtree filter, using the <get> protocol operation high-level subtree filter, using the <get-config> protocol operation high-level XPath filter, using the <get> protocol operation high-level XPath filter, using the <get-config> protocol operation All the high-level retrieval operations support the $$with-defaults system variable. The <with-defaults> parameter will be added the the NETCONF PDU if this variable is set to a value other than 'none' (the default). This system variable will be used as the default if not entered directly. session1> sget /system --with-defaults=$$with-defaults This parameter can also be specified directly, each time the command is used. session1> xget-config //ifmtu --with-defaults=trim Version Page 75

76 The $$bad-data system variable is used to control how invalid operations and data are sent to the server. The xget and xget-config commands are affected by this parameter. If the :xpath capability was not advertised by the server when the session started, an error or warning may occur if these commands are used. If any data is received that yangcli-pro does not understand, then a warning message will be printed and the data will be treated as if it was defined with the YANG 'anyxml' data type Modifying Data The following commands are available to modify generic data (i.e., an arbitrary subset of an entire NETCONF database): command commit create delete delete-config discard-changes edit-config fill insert lock merge replace save unlock description raw NETCONF <commit> operation high-level <edit-config> operation, with nc:operation='create' high-level <edit-config> operation, with nc:operation='delete' raw NETCONF <delete-config> operation raw NETCONF <discard-changes> operation raw NETCONF <edit-config> operation fill a variable for re-use in other operations high-level <edit-config> operation, with YANG insert operation extensions lock a NETCONF database high-level <edit-config> operation, with nc:operation='merge' high-level <edit-config> operation, with nc:operation='replace' High level save operation, depending on the default target (candidate or running) unlock a NETCONF database All the high-level editing operations use the --target parameter reported by the server when the session started up. If the server did not report the :candidate or :writable-running capabilities, then there will be no writable target, and an error will occur if these commands are entered. All the high-level editing operations support the $$default-operation system variable. The <default-operation> parameter will be added the the NETCONF <edit-config> PDU if this variable is set to a value other than 'not-used'. The default is the enumeration 'none', which means do not use any default operation, and only use the explicit nc:operation attribute. All the high-level editing operations support the $$test-option system variable. The <test-option> parameter will be added the the NETCONF <edit-config> PDU if this variable is set to a value other than 'none' (the default). This system variable will be used as the default if not entered directly. session1> replace /interfaces/interface[name='eth0']/ifmtu \ Version Page 76

77 --test-option=$$test-option \ --value=$newvalue YumaPro yangcli-pro Manual This parameter can also be specified directly, each time the command is used. session1> $newvalue = 1518 session1> replace /interfaces/interface[name='eth0']/ifmtu \ --test-option=test-only \ --value=$newvalue All the high-level retrieval operations support the $$error-option system variable. The <error-option> parameter will be added the the NETCONF <edit-config> PDU if this variable is set to a value other than 'none' (the default). This system variable will be used as the default if not entered directly. session1> replace /interfaces/interface[name='eth0']/ifmtu \\ --error-option=$$error-option \ --value=1518 This parameter can also be specified directly, each time the command is used. session1> replace /interfaces/interface[name='eth0']/ifmtu \ --error-option=rollback-on-error \ --value=1518 The high level save command is mapped to other commands, depending on the capabilities reported by the server. :candidate capabilities :writable-running commit <none> save command real command(s) :startup copy-config --source=running \ --target=startup Using Notifications The create-subscription command is used to start receiving notifications. The netconfd-pro server will include a <sequence-id> element in any notification that is saved in the replay buffer. This unsigned integer can be used to help debug notification filters (i.e., if non-consecutive <sequence-id> values are received, then the notification was filtered, or dropped due to access control policy). Version Page 77

78 If any replay notifications are desired, then the --starttime parameter must be included. At the end of the stored notifications, the server will send the <replaycomplete> event. This notification type is not saved, and will not be found in the server replay buffer, if replay is supported by the server. The netconfd-pro server will not include a <sequence-id> element in this notification type. If the notification subscription should stop at a certain time, then the --stoptime parameter must be included. At the end of the stored notifications, the server will send the <replaycomplete> event, followed by the <notificationcomplete> event.. This notification type is not saved, and will not be found in the server replay buffer, if replay is supported by the server. The netconfd-pro server will not include a <sequence-id> element in this notification type. Notifications are printed to the log, using the current $$display-mode system variable setting, when and if they are received. Notifications are also logged. Use the eventlog command to access the notifications stored in the event log Configuration Parameters That Affect Sessions The --server, --user, and --password configuration parameters can be used to start a NETCONF session automatically at startup time. The connect command will only be attempted at startup time if the --server parameter is present. If all 3 of these parameters are present at startup time, then no interactive prompting for additional optional parameters will be done. Instead the connect command will be invoked right away. During normal operation, the --optional configuration parameter, or the $$optional system variable, can be used to control interactive prompting for optional parameters. The --server parameter is saved in the $$server system variable, which can be overwritten at any time. If set, this will be used as the initial default value for the --server parameter in the connect command. The --fixorder configuration parameter can be used to control XML PDU ordering. If set to 'true', then the PDU will be reordered (if needed),to use the canonical order, according to the YANG specification. If 'false', the order parameters are entered at the command line will be their NETCONF PDU order as well. The default is 'true'. To send the server incorrectly ordered data structures on purposes, set this parameter to 'false'. The --user parameter is saved in the $$user system variable, which can be overwritten at any time. If set, this will be used as the initial default value for the --user parameter in the connect command. The --with-defaults configuration parameter, or the $$with-defaults system variable, can be used to set the default value for the 'with-defaults' parameter extension for the NETCONF get, get-config, and copy-config protocol operations. The default is 'none'. The --error-option configuration parameter, or the $$error-option system parameter, can be used to set the default value for the --error-option parameter for the NETCONF edit-config protocol operation. The default is 'none'. The --test-option configuration parameter, or the $$test-option system parameter, can be used to set the default value for the --test-option parameter for the NETCONF edit-config protocol operation. The default is 'none'. The --bad-data configuration parameter, or the $$bad-data system variable, can be used to control how yangcli-pro handles parameter values that are known to be invalid, or usage of optional protocol operations that the current session does not support. The default value is 'check'. To use yangcli-pro in a testing mode to send the server incorrect data on purpose, set this parameter to 'warn' or 'ignore' Trouble-shooting NETCONF Session Problems If the NETCONF session does not start for any reason, one or more error messages will be printed, and the prompt will indicate 'idle' mode. This section assumes that the server is netconfd-pro, and these debugging steps may not apply to all NETCONF agents. Version Page 78

79 If the NETCONF session does not start: make sure the server is reachable try to 'ping' the server and see if it responds make sure the SSH server is responding try to login in to the server using normal SSH login on port 22 make sure a firewall is not blocking TCP port 830 try to connect to the NETCONF server using the --port=22 option make sure the netconf-subsystem is configured correctly in /etc/ssh/sshd_config there should be the proper configuration commands for NETCONF to work. For example, the netconfd-pro server configuration might look like this: Port 22 Port 830 Subsystem netconf /usr/sbin/netconf-subsystem make sure the netconfd-pro server is running. Use the unix 'ps' command, or check the netconfd-pro log file, to make sure it is running. ps -alx grep netconf (look for 1 'netconfd-pro and N 'netconf-subsystem' -- 1 for each active session) make sure the user name is correct This must be a valid user name on the system make sure the password is correct This must be the valid password (in /etc/passwd or /etc/shadow) for the specified user name If the NETCONF session stops responding: make sure the server is still reachable try to 'ping' the server and see if it responds make sure the SSH server is still responding try to login in to the server using normal SSH login on port 22 If the NETCONF server is not accepting a certain command: make sure the command (or parameters used in the command) is actually supported by the server. There may be features, when statements, or deviation statements that indicate the server does not support the command or one or more of its parameters. Version Page 79

80 make sure that access control configured on the server is not blocking the command. The error-tag should be 'access-denied' in this case. If the NETCONF server is not returning the expected data in a <get> or <get-config> protocol operation:: Make sure all the parameters are supported by the server the :xpath capability must be advertised by the server to use the 'select' attribute in the <get> or <getconfig> operations the :with-defaults capability must be advertised by the server to use the <with-defaults> parameter if using a filter, try to retrieve the data without a filter and see if it is there make sure that access control configured on the server is not blocking the retrieval. There will not be any error reported in this case. The server will simply skip over any unauthorized data, and leave it out of the <rpcreply>. set the logging level to debug2 or higher, and look closely at the PDUs being sent to the server. Set the display mode to a value other than 'plain' to make sure the correct namespaces are being used in the request. If an <edit-config> operation is failing unexpectedly: make sure that access control configured on the server is not blocking the request. The error-tag should be 'access-denied' in this case. make sure an unsupported parameter or parameter value is not used <test-option> is not supported unless the :validate capability is advertised by the server <error-option> = 'rollback-on-error' is not supported unless the :rollback-on-error capability is advertised by the server if the request contains an edit to a nested data structure, make sure the parent data structure(s) are in place as expected. The <default-operation> parameter is set to 'none' in the high level editing operations, so any data 'above' the edited data must already exist. set the logging level to debug2 or higher, and look closely at the PDUs being sent to the server. Set the display mode to a value other than 'plain' to make sure the correct namespaces are being used in the request. 2.9 Automated Testing Automated regression testing is provided using test-suite templates to describe actions and expected responses and results. The test-suite command is used to access this feature. Tests rely on named sessions in order to send commands from different sessions. Each test step can be directed at a different session. The locking example in a later section shows how test step commands can be either expected to succeed (e.g., first session attempts <lock> command) and fail (e.g., second session attempts <lock> but the datastore is already locked). The start-session command is usually used within the setup section for each session required in all of the tests within the test-suite. The server must already be running. (TBD: start-server and stop-server commands will be available in a future release.) The setup and cleanup sections defined within a test suite are called CLI text blocks. They use a special configuration file syntax which allows maximum flexibility for the test designer. These sections begin and and with square brackets ('[' and ']') instead of angle brackets ('{' and ''). There are no leafs within these containers. Instead they contain plain command lines exactly like a script. Version Page 80

81 2.9.1 Test Templates The test suite file structure is shown below: test-suite-file: collection of test-suites in a single file. Multiple files can be loaded. If the --autotest CLI parameter is 'true' (default) then yangcli-pro will look for the default test file, called $HOME/.yumapro/yangcli_pro_tests.conf. test-suite: collection of tests. Each test-suite has an optional 'setup' section which is executed once before the tests are run, and an optional 'cleanup' section that is run after all the tests have run test: collection of steps to perform a specific test step: a command to be executed locally or remotely to a specified session. Each step for a remote command can be configured to check the server response received. Version Page 81