Invoking yangcli-pro 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)
  

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.

It can also be configured and changed at run-time by the user (yp-shell only).

If the --prompt CLI parameter or $$prompt configuration variable is used to set the prompt to a user-specified value, then that will be the prompt shown in Idle Mode, and also used as the base prompt string in Config Mode. See the --prompt parameter for more details.

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

Default session:

andy@myserver#

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.

andy@myserver> sget

Enter a number of the selected case statement:

  1: case varref:
       leaf varref
  2: case from-cli:
       leaf target
       leaf optional
       anyxml value

Enter choice number [1 - 2]:
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>

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.

Using the ncx:default-parm Extension

Each command may define a default parameter, by placing an ncx:default-parm extension in the rpc input section in the YANG rpc statement. This extension allows less typing in yangcli-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	Default Parameter
action	target
alias	var
aliases	show
cd	dir
connect	server
create	target
elif	expr
else	expr
if	expr
eventlog	show
fill	target
help	command
history	show
insert	target
load	module
log-debug	msg
log-error	msg
log-info	msg
log-warn	msg
merge	target
mgrload	module
recall	index
replace	target
run	script
set-log-level	log-level
sget	target
sget-config	target
sget-data	target
xget	select
xget-config	select
xget-data	select
while	expr

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. If --break-key-mode=command then Control-C can also be used to cancel a 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 YumaPro CLI Reference for more details.

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" : -4200
  }
 }
}
"""

Example script using XML:

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

Restrictions:

• Only the following YANG data node types are supported:

  • container

  • list

  • anyxml

  • anydata

  • input

  • output

• Starting in release 22.10-13, the following data node types are also supported:

  • leaf

  • leaf-list

• The maximum length of an input line, including all inline data, is 65535 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 External XML

It is possible to specify command parameters and even the entire command with an external XML file. This file needs to be located in the data path, such as the $HOME/data directory.

The CLI parameter --use-rawxml affects the parsing of the external XML file. By default, the XML will be parsed and converted to internal data format. If --use-rawxml=true is used then the file will be used as-is if the XML file is invalid.

If this parameter is ‘false’ then xmlns attributes will be ignored in the external XML file.

External XML Parameters

A parameter can be specified using an external XML file using the @<filename> syntax

> get filter=@myfilter.xml


andy@localhost> get filter=@myfilter.xml

RPC Data Reply 6 for session 3 [default]:

rpc-reply {
  data {
    netconf-state {
      statistics {
        netconf-start-time 2019-12-03T01:30:04Z
        in-bad-hellos 0
        in-sessions 1
        dropped-sessions 0
        in-rpcs 5
        in-bad-rpcs 0
        out-rpc-errors 0
        out-notifications 0
      }
    }
  }
}

andy@localhost>

In this example, the contents of the <filter> element will be filled using the contents of the file “myfilter.xml”. The contents will be used as the child nodes of the <filter> element. This is suitable for sending subtree filters.

<netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
  <statistics/>
</netconf-state>

The message sent to the server:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="5" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get>
    <filter type="subtree">
      <netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
        <statistics/>
      </netconf-state>
    </filter>
  </get>
</rpc>

External XML Commands

It is possible to provide the entire command in the external XML file. In this case the top-level element must match the command, and the contents of this command will be used for the input parameters.

> $$use-rawxml = true

> get @myget.xml

The contents of the myget.xml contain a filter element using an XPath expression. In this case the prefixes need to be defined if any are used in the XPath expression. Note that the <get> operation needs a namespace definition as well or else the namespace will default to “yuma-ncx”.

<get xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <filter type="xpath" select="/n:netconf-state/n:statistics"
    xmlns:n="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring" />
</get>

Entering Special Characters in Strings

There are a number of characters that require special processing to be used in a command. These special characters are not normally used in administrative strings, but they are allowed in YANG.

Special Characters

Name	Print Char	Hex Value	Description
question mark	?	0x3F	Help Command
vertical bar	|	0x7C	Pipe Command
space, tab, etc.	whitespace	see table	Parameter Delimiter

If special characters are needed in the value for a string parameter, then they cannot be entered with an unquoted string. They must be entered in one of three ways:

• Single Quoted Strings

• Double Quoted Strings

• Inline XML For Strings

Help Key Must Be Quoted

The question mark character ? is used as the context-sensitive help key. In order to enter this character at all, the string in progress must be quoted. Otherwise the help text will be printed and the question mark key removed from the input.

• This applies to regular and config mode commands

Example:

> my-command my-parm="some-value-with-???"

Pipe Command Key Must Be Quoted

The vertical bar character | is used to start a pipe command. The command will not be interpreted correctly if this character is present in an unquoted string. It must be entered in a quoted string.

• This applies to regular commands but not config mode commands

Example:

> my-command my-parm='this|that|other'

XML Special Characters in Strings

XML special characters are handled automatically in strings.

XML Special Char	Char Entity	Hex Value
<	&lt;	0x3C
>	&gt;	0x3E

If these special XML characters are found in any string they are converted to character entities when the command is encoded in XML. The character entities must be used within inline XML.

Example request:

> sget '/CONTONE/LISTONE[name="abc \" < efghi >"]'

Example XML message for this command:

<rpc message-id="3"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <get>
  <filter type="subtree">
   <CONTONE xmlns="http://example.com/ns/yang/special_char">
    <LISTONE>
     <name>abc " &lt; efghi &gt;</name>
    </LISTONE>
   </CONTONE>
  </filter>
 </get>
</rpc>

Whitespace Characters in Strings

Whitespace characters allowed in strings are shown in the table below:

Whitespace Char	Escape String	Hex Value
horizontal tab	\t	0x09
line feed	\n	0x0A
carriage return	\r	0x0D
space	none	0x20

Example: Quoted string is not needed

> my-command my-parm=string-without-spaces

Example: Quoted string is needed

> my-command my-parm="string with spaces"

Special XPath String Handling

An escaped double quote within a double-quoted string for XPath may not be supported. The escaped double quotes within the string are not always converted back to plain double quotes.

WRONG:

The following example shows double quoted strings that will not work and are not supported:

> sget "/CONTONE/LISTONE[name=\"abc efghi\"]"

> sget "/CONTONE/LISTONE[name=\"abc \" efghi\"]"

Example Error if double quoted string is used in this way:

andy@dev1> sget "/CONTONE/LISTONE[name=\"abc \" efghi\"]"

Error: invalid predicate in expression '/CONTONE/LISTONE[name=\"abc \" efghi\"]'
0.22: error(245): wrong token type

Error: parse XPath target '/CONTONE/LISTONE[name=\"abc \" efghi\"]' failed
Error: invalid target parameter (wrong token type)

CORRECT:

It is OK to use single quotes if the content does not contain a single quote. Note that the plain quotation marks are used, not escaped quotation marks.

> sget '/CONTONE/LISTONE[name="abc efghi"]'

The escaped double quote \" in the example below is properly converted to a single char " when processed by the sget command:

> sget '/CONTONE/LISTONE[name="abc \" efghi"]'

If any XPath string value must contain single quotes, double quotes, and whitespace, then Inline XML For Strings must be used.

Single Quoted Strings

A single-quoted string:

• begins and ends with the apostrophe char (0x27)

• cannot contain the apostrophe char (0x27)

• does not interpret any quoted characters as escape strings

• preserves all quoted characters

Example: sget command with spaces and a double quote in a predicate

> sget '/CONTONE/LISTONE[name="abc \" efghi"]'

The <get> operation request sent to the server for this example:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="2"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <get>
  <filter type="subtree">
   <CONTONE xmlns="http://example.com/ns/yang/special_char">
    <LISTONE>
     <name>abc " efghi</name>
    </LISTONE>
   </CONTONE>
  </filter>
 </get>
</rpc>

Double Quoted Strings

A double-quoted string:

• begins and ends with the quotation mark char (0x22)

• can contain single quotes

• can contain escape sequences, which consist of two characters, starting with a backslash (0x5C), and followed by:

  • n: line feed

  • t: horizontal tab

  • ": quotation mark

  • \: backslash

Example: config mode edit request containing special chars:

# nacm groups group G3 user-name "fred\n\tone"

Example: <edit-config> request message for this config mode edit:

• Note the \n converted to actual newline and \t converted to an actual horizontal tab

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="9"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <edit-config>
  <target>
   <candidate/>
  </target>
  <default-operation>merge</default-operation>
  <test-option>set</test-option>
  <config>
   <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
    <groups>
     <group>
      <name>G3</name>
      <user-name>fred
    one</user-name>
     </group>
    </groups>
   </nacm>
  </config>
 </edit-config>
</rpc>

Inline XML For Strings

If a string parameter needs to contain double quotes, single quotes, and whitespace, then it might need to be encoded as inline XML instead of a quoted string.

Starting in release 22.10-13, inline XML can be used for a leaf or leaf-list object.

> sget target="""<target>/CONTONE/LISTONE[name="abc\" '  efghi"]</target>"""

The inline XML can be used even for the default parameter:

> sget """<target>/CONTONE/LISTONE[name="abc\" '  efghi"]</target>"""

Example: get request message sent for this command:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="15"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <get>
  <filter type="subtree">
   <CONTONE xmlns="http://example.com/ns/yang/special_char">
    <LISTONE>
     <name>abc" '  efghi</name>
    </LISTONE>
   </CONTONE>
  </filter>
 </get>
</rpc>

Example: Using Character Entity to Replace '>' Character

> sget """<target>/CONTONE/LISTONE[name="abc\" ' &gt; efghi"]</target>"""

The <get> request sent for this example:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="16"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <get>
  <filter type="subtree">
   <CONTONE xmlns="http://example.com/ns/yang/special_char">
    <LISTONE>
     <name>abc" ' &gt; efghi</name>
    </LISTONE>
   </CONTONE>
  </filter>
 </get>
</rpc>

The server parses the > character entity when the XML is converted to an internal val_value_t structure.

agt_rpc: parse RPC input state

  yuma-netconf:input {
    filter {
      special_char:CONTONE {
        LISTONE {
          name "abc" ' > efghi"
        }
      }
      filter.metaQ
        yuma-ncx:type subtree
    }
  }

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)

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

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

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

# reply shown with --display-mode=plain
data {
   interfaces {
     interface eth0 {
            name eth0
            ifMtu 1500
      }
     interface eth1 {
            name eth1
            ifMtu 1518
      }
   }
}

Special Parameter Handling

Some special handling of YANG data structures is done by the script interpreter. This special handling only apples to command mode.

Password Parameter

Some special handling is done for YANG leafs that contain sensitive information such as a login password. It is important to prevent cleartext passwords from being printed in log files.

The best way to handle passwords is with the 'crypt-hash' typedef defined in the iana-crypt-hash.yang module, and avoid entering any password in cleartext.

If passwords are entered in cleartext, there are YANG extensions that can be used to treat them as special parameters:

• ncx:password : Treat the leaf as a password

• oc-ext:openconfig-hashed-value : Treat the leaf as an OpenConfig password

The password will be printed as eight asterisk characters ******** if entered at a parameter prompt.

Hidden Parameter

Some special handling is done for YANG data nodes that should be hidden from the CLI user.

• ncx:hidden : YANG extension to make the YANG data node hidden from all user protocols

• ywx:hidden-from-cli: YANG extension to make the YANG data node hidden from only the CLI

Confirmed Parameter

Some special handling is done for YANG leaf parameters that should be confirmed by the user by entering the same value again.

• ywx:confirm-data: YANG extension to use to identify a leaf as a parameter that must be entered correctly a second time by the user to confirm the value.

• --confirm-data-retries: CLI parameter to control how many attempts the user gets to re-enter the parameter value correctly.

If the parameter value is not confirmed by the user then the current command will be canceled.

Containers

Mandatory containers will be filled (in interactive mode) by default. The '$$optional' variable should be set to 'true' to cause optional containers to be filled as well.

Container DataStore Selection

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 as the 'contents' of the container parameter.

andy@myserver> sget-config /system source=candidate

This behavior is only supported for the following basic structure:

• container with 1 child that is a choice

• child choice has 1 or more cases

• each child case contains one leaf with type 'empty'

Example: The special handling is supported for these commands for the source' parameter:

• get-config

• sget-config

• xget-config

Container Child Node Selection

A leaf or leaf-list child node within a container can be set from the command line, without requiring interactive editing, inline XML, or external XML files.

A container name can be followed by a forward slash '/', followed by a leaf or leaf-list name. The syntax for setting a simple value is allowed after the leaf or leaf-list name.

Example: start a YANG Push periodic subscription of the running datastore:

> establish-subscription datastore=running periodic/period=3000

There are some restrictions at this time:

• Only top-level containers or containers within top-level choices are supported

• Tab completion for this mode is not supported

Choices and Cases

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

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

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

# this is not allowed because 'help-mode' is not complete
> 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.

Boolean Data Type

The YANG boolean data type is supported.

• The values true, 1, and "1" will be accepted for 'true'.

• The values false, 0, and "0" will be accepted for 'false'.

Command Completion

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

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

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

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

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

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

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

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

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

Command list example: no NETCONF session is active:

> <hit tab key>
cd       fill     history  mgrload  quit     run
connect  help     list     pwd      recall   show

Command list example: NETCONF session is active

[email protected]> <hit tab key>
cd                   get-schema           recall
close-session        help                 replace
commit               history              restart
connect              insert               run
copy-config          kill-session         save
create               list                 sget
create-subscription  load                 sget-config
delete               load-config          show
delete-config        lock                 shutdown
discard-changes      merge                unlock
edit-config          mgrload              validate
fill                 no-op                xget
get                  pwd                  xget-config
get-config           quit

Command Line Editing

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

• Refer to the complete user guide for information on configuring libtecla.

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

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

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

  edit-mode vi
  

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

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

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

The following table shows the most common default key bindings:

Common editing key bindings

Command	Description
^C	clear screen
^F	cursor right
^B	cursor-left
^A	beginning of line
^E	end of line
^U	delete line
M-f	forward-word
M-b	backward word
^P	up history
^N	down history

Command History

Each command line is saved in the command history buffer, unless a password is being entered in parameter mode. A command line can be recalled using the recall command.

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

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

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

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

• clear: clear the history buffer

• save: save the history buffer to a file

• load: load the history buffer from a file

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

If --autohistory is ‘true’, then by default, the command line history buffer is loaded from the file $HOME/.yumapro.yangcli_pro_history This behavior can be changed by setting the --history-file configuration parameter to the file specification to use instead of the default file location. The same parameter needs to be used each time the program is loaded in order to maintain the same history file.

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:

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

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

Refer to the history command section for more details on this 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 section for more details. Logging capabilities are also discussed in more detail in the YumaPro User Manual.