Provided by: yangcli_2.13-2.1build2_amd64 
NAME
yangcli - YANG-based NETCONF-over-SSH client application
SYNOPSIS
yangcli [parameter=value...]
yangcli --help [brief | normal | full]
yangcli --version
DESCRIPTION
yangcli is a Command Line Interface for the NETCONF protocol. It uses the YANG data
modeling language to manage the NETCONF content layer. This version of yangcli supports
the YANG data modeling language defined in RFC 6020.
Normal Mode:
An interactive CLI shell with command line history.
Autostart-mode:
If the 'server' parameter is present, then yangcli will
attempt to connect to that server upon startup. If the
'user' and 'password' parameters are also present, then
the user will not be prompted before the connection
is attempted. This parameter will be processed first,
if script-mode or batch-mode is used.
Script-mode:
If the 'run-script' or 'run-command' parameter is present,
then the specified script or command will be run automatically
upon startup.
Batch-mode:
If the 'batch-mode' parameter is present, then either the
'run-script' or 'run-command' parameter will be invoked, if
present, and then the program will exit.
USAGE
Parameters can be entered in any order, and have the form:
[start] name [separator [value]]
where:
start == 0, 1, or 2 dashes (foo, -foo, --foo)
name == parameter name
Parameter name completion will be attempted
if a partial name is entered.
separator == whitespace or equals sign (foo=bar, foo bar)
value == string value for the parameter.
Strings with whitespace need to be double quoted
(--foo="some string")
Some examples of valid command line parameters:
foo=3
-foo=3
--foo=3
foo 3
foo=fred
--foo "fred flintstone"
Partial parameter names can be entered if they are unique.
OPTIONS
--aliases-file[=filespec]
Specifies the yangcli command aliases file to use. The default is
~/.yuma/.yangcli_aliases.
--alt-names=boolean
Altername name match mode to use for UrlPath name searches. The default is true
(allow matches on alt-name extension).
--autoaliases=boolean
Controls whether the yangcli command aliases will be saved at exit and loaded at
startup. If true, the 'aliases-file' parameter will be used if it is set, or else
the default aliases file will be used (~/.yuma/.yangcli_aliases), for loading and
saving the yangcli command aliases. If false, the yangcli command aliases will
only be stored and loaded manually with the aliases command. The default is true.
--autocomp=boolean
Controls whether partial keywords will be checked for interactive or script
commands. If true (the default), the first match for a partial keyword will be
used if no definition is found for a command name or parameter name. If false,
then exact command and parameter name values must be given.
--autohistory=boolean
Controls whether the command line history buffer will be saved at exit and loaded
at startup. If true, the default history file will be used
(~/.yuma/.yangcli_history) for loading and saving the history buffer. This is the
default value. If false, the history buffer will only be stored and loaded
manually with the history command.
--autoload=boolean
Controls whether any YANG content modules will be automatically loaded upon startup
or upon session startup with a server. This is the default value. If false, the
'load-module' command must be used to explicitly load all the desired definition
modules.
--autouservars=boolean
Controls whether the yangcli user variables will be saved at exit and loaded at
startup. If true, the 'uservars-file' parameter will be used if set, or else the
default user variables file will be used (~/.yuma/yangcli_uservars.xml), for
loading and saving the yangcli user variables. If false, the yangcli user
variables will only be stored and loaded manually with the uservars command. The
default is true.
--bad-data=enum
Specifies how invalid user input from the CLI will be handled when filling PDUs for
remote operations.
enum values:
ignore
Silently accept invalid PDU and data model
parameters. Intended for advanced server
testing mode only.
warn
Warn, but accept invalid PDU and data model
parameters.
check
Prompt the user to keep the invalid value
or re-enter the value.
error
Prompt the user to re-enter the invalid value.
--batch-mode
If present, the interactive CLI will not be used. A script should be provided with
the 'run-script' parameter, or a command provided with the 'run-command' parameter,
or else the program will simply exit. If the auto-connect mode is enabled, then
this will mode simply test if a NETCONF session can be established, then exit.
--config=filespec
The name of the configuration file to use. Any parameter except this one can be
set in the config file. The default config file /etc/yuma/yangcli.conf will be not
be checked if this parameter is present.
--datapath=list
Internal file search path for configuration data files. Overrides the
YUMA_DATAPATH environment variable.
--default-module=string
Default module name string to use before 'netconf' and 'yangcli' are tried. The
module prefix may need to be used for other modules.
--deviation=string
This parameter identifies a YANG module that should only be checked for deviation
statements for external modules. These will be collected and applied to the real
module(s) being processed.
Deviations are applied as patches to the target module. Since they are not
identified in the target module at all (ala imports), they have to be specified
explicitly, so they will be correctly processed. Zero or more instances of this
parameter are allowed.
--display-mode=enum
Controls how values are displayed during output to STDOUT or a log file.
enum values:
plain
Plain identifier without any prefix format.
prefix
Plain text with XML prefix added format.
module
Plain text with module name as prefix added format.
xml
XML format.
xml-nons
XML format, but without any namespace (xmlns) attributes.
json
JSON format.
--dump-session=<filespec-base>
Filespec base for dumping the raw netconf traffic data and timestamp information.
Example:
--dump-session=/tmp/ses- The following files are created:
* /tmp/ses-out - session data sent to server
* /tmp/ses-in - session data received from server
* /tmp/ses-out.ts - size and timestamp for data transmitted
* /tmp/ses-in.ts - size and timestamp for data received
--echo-replies=boolean
Allow RPC replies to be echoed to the log or STDOUT.
If true, <rpc-reply> messages containing data will be output to the log, if log-
level is 'info' or higher. If false, <rpc-reply> messages containing data will
not be output to the log, regardless of the value of log-level.
--echo-requests=boolean
Allow RPC requests to be echoed to the log or STDOUT.
If true, <rpc> messages will be output to the log, if log-level is 'info' or
higher. If false, <rpc> messages will not be output to the log, regardless of the
value of log-level.
--feature-disable=module:feature
Identifies a feature which should be considered disabled. Zero or more entries are
allowed.
--feature-enable-default=boolean
If true (the default), then features will be enabled by default. If false, then
features will be disabled by default.
--feature-enable=module:feature
Identifies a feature which should be considered enabled. Zero or more entries are
allowed.
--fixorder=boolean
Controls whether PDU parameters will be automatically sent to the server in the
correct order. If true, then canonical order will be used. This is the default
value. If false, the specified order will be used.
--force-target=enum
Controls whether the candidate or running configuration datastore will be used as
the default edit target, when both are supported by the server.
enum values:
candidate
Force default edit target to be candidate.
running
Force default edit target to be running.
--help Print this help text and exit. The help-mode choice (--brief, --normal, or --full)
may also be present to control the amount of help text printed.
--home=dirspec
Directory specification for the home directory to use instead of HOME.
--indent=number
Number of spaces to indent (0..9) in formatted output. The default is 2 spaces.
--log=filespec
Filespec for the log file to use instead of STDOUT. If this string begins with a
'~' character, then a username is expected to follow or a directory separator
character. If it begins with a '$' character, then an environment variable name is
expected to follow.
--log-append
If present, the log will be appended not over-written. If not, the log will be
over-written. Only meaningful if the log parameter is also present.
--log-level=enum
Sets the debug logging level for the program.
enum values:
off
error
warn
info
debug
debug2
debug3
debug4
--match-names=enum
Match mode to use for UrlPath name searches.
enum values:
exact
The name must exactly match the node name
for all characters in both name strings.
exact-nocase
The name must match the node name
for all characters in both name strings.
Strings are not case-sensitive.
one
The name must exactly match the first N
characters of just one node name, which
must be the only partial name match found.
one-nocase
The name must exactly match the first N
characters of just one node name, which
must be the only partial name match found.
Strings are not case-sensitive.
first
The name must exactly match the first N
characters of any node name. The first one
found will be used.
first-nocase
The name must exactly match the first N
characters of any node name. The first one
found will be used. Strings are not
case-sensitive.
--modpath=list
Directory search path for YANG and YIN files. Overrides the YUMA_MODPATH
environment variable.
--module=string
YANG or YIN source module name to load upon startup. If this string represents a
filespec, ending with the .yang or .yin extension, then only that file location
will be checked.
If this string represents a module name, then the module search path will be
checked for a file the .yang or .yin extension.
If this string begins with a '~' character, then a username is expected to follow
or a directory separator character. If it begins with a '$' character, then an
environment variable name is expected to follow.
~/some/path ==> <my-home-dir>/some/path
~fred/some/path ==> <fred-home-dir>/some/path
$workdir/some/path ==> <workdir-env-var>/some/path
--ncport=number
The NETCONF port number to use for starting sessions. If not present, then port
830, followed by port 22, will be tried.
--password=string
User password to use for NETCONF sessions. If none, then user will be prompted
before connecting.
--private-key=string
Contains the file path specification for the file containing the client-side
private key. If both 'public-key' and 'private-key' files are present, the client
will attempt to connect to the server using these keys. If this fails, or not
done, then password authentication will be attempted.
--protocols=bits
Specifies which protocol versions the program or session will attempt to use. Empty
set is not allowed. Default is to enable all protocols.
bit values:
netconf1.0
RFC 4741 base:1.0
netconf1.1
RFC xxxx base:1.1
--public-key=string
Contains the file path specification for the file containing the client-side public
key. If both 'public-key' and 'private-key' files are present, the client will
attempt to connect to the server using these keys. If this fails, or not done,
then password authentication will be attempted.
--run-command=string
The specified command will be invoked upon startup. If the auto-connect parameters
are provided, then a session will be established before running the command.
--run-script=string
The specified script will be invoked upon startup. If the auto-connect parameters
are provided, then a session will be established before running the script. If a
quoted string is used, then any parameters after the script name will be passed to
the script.
--runpath=list
Internal file search path for script files. Overrides the YUMA_RUNPATH environment
variable.
--server=string
IP address or DNS name of the NETCONF server target to use for the auto-startup
mode, or as the default value when starting a new session.
--subdirs=boolean
If false, the file search paths for modules, scripts, and data files will not
include sub-directories if they exist in the specified path.
If true, then these file search paths will include sub-directories, if present.
Any directory name beginning with a dot (.) character, or named CVS, will be
ignored. This is the default mode.
--time-rpcs=boolean
Measure the round-trip time of each <rpc> request and <rpc-reply> at the session
level. Echo the elapsed time value to screen if in interactive mode, as well as
the log if the log is a file instead of stdout.
--timeout=number
The number of seconds to wait for a response from the server before declaring a
timeout. Zero means do not timeout at all.
--transport=enum
Identifies the transport protocol that should be used. This is the default that
will be used or the value used in auto-connect mode. The value can also be
provided when invoking the 'connect' command.
enum values:
ssh
NETCONF over SSH.
RFC 4742; RFC 6242
tcp
NETCONF over TCP.
If this enum is selected, then the default --ncport
value is set to 2023, and the --protocols value
is set to netconf1.0. The --password value will
be ignored.
--use-xmlheader=
Specifies how file result variables will be written for XML files. Controls
whether the XML preamble header will be written or not.
--user=string
User name to use for NETCONF sessions. This value will be used in auto-startup
mode, or as the default value when starting a new session.
--uservars-file=filespec
Specifies the yangcli user variables file to use. The default is
~/.yuma/yangcli_uservars.xml.
--version
Print the program version string and exit.
--warn-idlen=number
Control whether identifier length warnings will be generated. The value zero
disables all identifier length checking. If non-zero, then a warning will be
generated if an identifier is defined which has a length is greater than this
amount. range: 0 | 8 .. 1023. The default value is 64.
--warn-linelen=number
Control whether line length warnings will be generated. The value zero disables
all line length checking. If non-zero, then a warning will be generated if the
line length is greater than this amount. Tab characters are counted as 8 spaces.
range: 0 | 40 .. 4095. The default value is 72.
--warn-off=number
Control whether the specified warning number will be generated and counted in the
warning total for the module being parsed. range: 400 .. 899. This parameter may
be entered zero or more times.
--yuma-home=string
Directory for the yuma project root to use. If present, this directory location
will override the YUMA_HOME environment variable, if it is present. If a zero-
length string is entered, then the YUMA_HOME environment variable will be ignored.
SEARCH PATH
When a module name is entered as input, or when a module or submodule name is specified in
an import or include statement within the file, the following search algorithm is used to
find the file:
1) file is in the current directory
2) YUMA_MODPATH environment var (or set by modpath parameter)
3) $HOME/modules directory
4) $YUMA_HOME/modules directory
5) $YUMA_INSTALL/modules directory OR
default install module location, '/usr/share/yuma/modules'
By default, the entire directory tree for all locations (except step 1) will be searched,
not just the specified directory. The subdirs parameter can be used to prevent sub-
directories from being searched.
Any directory name beginning with a dot character (.) will be skipped. Also, any
directory named CVS will be skipped in directory searches.
ERROR LOGGING
By default, warnings and errors are sent to STDOUT.
A log file can be specified instead with the log' parameter.
Existing log files can be reused with the 'logappend' parameter, otherwise log files are
overwritten.
The logging level can be controlled with the log-level parameter.
The default log level is 'info'. The log-levels are additive:
off: suppress all errors (not recommended!)
A program return code of '1' indicates some error.
error: print errors
warn: print warnings
info: print generally interesting trace info
debug: print general debugging trace info
debug2: print verbose debugging trace info
debug3: print very verbose debugging trace info
debug4: print maximum debugging trace info
ENVIRONMENT
The following optional environment variables can be used to control module search
behavior:
HOME The user's home directory (e.g., /home/andy)
YUMA_HOME
The root of the user's Yuma work directory (e.g., /home/andy/swdev/netconf)
YUMA_INSTALL
The root of the directory that yangdump is installed on this system (default is,
/usr/share/yuma)
YUMA_DATAPATH
Colon-separated list of directories to search for data files. (e.g.:
'./workdir/data-files:/home/andy/test-data') The datapath parameter will override
this environment variable, if both are present.
YUMA_MODPATH
Colon-separated list of directories to search for modules and submodules. (e.g.:
'./workdir/modules:/home/andy/test-modules') The modpath parameter will override
this environment variable, if both are present.
YUMA_RUNPATH
Colon-separated list of directories to search for script files. (e.g.:
'./workdir/scripts:/home/andy/scripts') The runpath parameter will override this
environment variable, if both are present.
CONFIGURATION FILES
yangcli.conf
YANG config file The default is: /etc/yuma/yangcli.conf
An ASCII configuration file format is supported to store command line parameters.
The config parameter is used to specify a specific config file, otherwise the
default config file will be checked.
- A hash mark until EOLN is treated as a comment
- All text is case-sensitive
- Whitespace within a line is not significant
- Whitespace to end a line is significant/
Unless the line starts a multi-line string,
an escaped EOLN (backslash EOLN) is needed
to enter a leaf on multiple lines.
- For parameters that define lists, the key components
are listed just after the parameter name, without
any name, e.g.,
interface eth0 {
# name = eth0 is not listed inside the braces
ifMtu 1500
ifName mySystem
}
A config file can contain any number of parameter sets for different programs.
Each program must have its own section, identifies by its name:
# this is a comment
yangcli {
log-level debug
default-module yuma-interfaces
}
FILES
The following data files must be present in the module search path in order for this
program to function:
* YANG module library
default: /usr/share/yuma/modules/
* yangcli command aliases
default: ~/.yuma/.yangcli_aliases
CLI parameters: --autoaliases, --aliases-file
See the 'aliases' and 'alias' command for details.
The format of the aliases file is text.
A comment is a line that begins with a '#' character,
and will be ignored. Comments are not saved if the
--autoaliases=true parameter value is used.
Single or double quotes can be used.
Example aliases file:
---------------------
g=get
gc=get-config
gcnacm='sget-config --source=running /nacm'
geteth0="xget /interfaces/interface[name='eth0']"
* yangcli user variables
default: ~/.yuma/yangcli_uservars.xml
CLI parameters: --autouservars, --uservars-file
See the 'uservars' command for details.
The format of the uservars file is XML.
Refer to the 'vars' container in yangcli.yang
for a definition of the XML contents.
DIAGNOSTICS
Internal diagnostics may generate the following type of message if any bugs are detected
at runtime:
[E0]
filename.c:linenum error-number (error-msg)
AUTHORS
Andy Bierman, <andy at netconfcentral dot org>
Vladimir Vassilev, <vladimir at lightside-instruments dot com>
SEE ALSO
netconf-subsystem(1) netconfd(1)