Page MenuHomeVyOS Platform

CLI Shell API
Updated 366 Days AgoPublic

Version 1 of 3: You are viewing an older version of this document, as it appeared on Apr 19 2020, 9:24 PM.

Since release 6.2 (Mendocino) Vyatta has an API for working with
configuration from shell scripts. Its binary is
/opt/vyatta/sbin/my\_cli\_shell\_api and has symbolic link at
/bin/cli-shell-api. This page describes methods of the API as of
Vyatta 6.4 (Oxnard) release.

For a less technical tutorial, see [Shell script
tutorial](Shell_script_tutorial "wikilink") page.

Definitions

Active config is config, currently used by system.

Working config is config we are making during configuration session.

Effective config {#effective_config}

The definition of \"effective\" is different under these two scenarios.

  1. When used outside a config session, \"effective\" == \"active\". In other words, in such cases the effective config is the same as the running config.
  2. When used during a config session, a config path (leading to either a \"node\" or a \"value\") is \"effective\" if ANY of the following is true.
  • active && working\ Path is in both active and working configs, i.e., unchanged.
  • !active && working && committed\ Path is not in active, has been set in working, AND has already been committed, i.e., \"commit\" has successfully processed the addition/update of the path.
  • active && !working && !committed\ Path is in active, has been deleted from working, AND has not been committed yet, i.e., \"commit\" (per priority) has not processed the deletion of the path yet, or it has been processed but failed.

Note: during commit, deactivate has the same effect as delete. So in
such cases, as far as these functions are concerned, deactivated nodes
don\'t exist.

Method reference {#method_reference}

It is invoked in format:

cli-shell-api <method>{=html} <configuration path>{=html}

Currently API has the following methods:

+----------------------+----------------------+----------------------+

MethodArgumentsPurpose

+======================+======================+======================+

getSessionEnvSession identifierReturns environment
variables needed for
configuration
session to work[^4]

+----------------------+----------------------+----------------------+

getEditEnvConfiguration pathReturns environment
variables for edit
level specified in
argument.

+----------------------+----------------------+----------------------+

getEditUpEnvNoneReturns environment
variables for edit
level above current
edit level. Returns
string \"Already at
the top level\" when
ran at the top edit
level.

+----------------------+----------------------+----------------------+

getEditResetEnvNoneReturns environment
variables for the
top level.

+----------------------+----------------------+----------------------+

editLevelAtRootNoneReturns 0 if current
edit level is top
level, 1 otherwise

+----------------------+----------------------+----------------------+

getCompletionEnvCommand andReturns environment
component (e.g.variables needed for
\"set service\" orcommand completion
\"edit firewall\")to work.

+----------------------+----------------------+----------------------+

getEditLevelStrNoneReturns current edit
level.

+----------------------+----------------------+----------------------+

markSessionUnsavedNoneMark current
configuration
session unsaved.

+----------------------+----------------------+----------------------+

unmarkSessionUnsavedNoneReset session
unsaved flag.

+----------------------+----------------------+----------------------+

sessionUnsavedNoneReturns 0 when
session unsaved flag
is set, 1 otherwise.

+----------------------+----------------------+----------------------+

setupSessionNoneInitiate a
configuration
session. Needs
environment to be
set properly, see
getSessionEnv.

+----------------------+----------------------+----------------------+

sessionChangedNoneReturns 0 if
configuration was
changed from current
session, 1
otherwise.

+----------------------+----------------------+----------------------+

teardownSessionNoneEnd current
configuration
session.

+----------------------+----------------------+----------------------+

inSessionNoneReturns 0 if
configuration
session is set up, 1
otheriwise.

+----------------------+----------------------+----------------------+

existsConfiguration pathReturns 0 if
specified
configuration path
exists (either in
currently used or
built during the
session config), 1
otherwise.

+----------------------+----------------------+----------------------+

existsActiveConfiguration pathReturns 0 if
specified node
exists in the
current active
(running)
configuration, 1
otherwise.

+----------------------+----------------------+----------------------+

existsEffectiveConfiguration pathReturns 0 if
specified path
exists in effective
config, 1 otherwise

+----------------------+----------------------+----------------------+

isMultiConfiguration pathReturns 0 if
specified node is a
multi node (i.e. may
have more than one
value), 1 otherwise

+----------------------+----------------------+----------------------+

isTagConfiguration pathReturns 0 if
specified node is a
tag node, 1
otherwise

+----------------------+----------------------+----------------------+

Configuration path???

+----------------------+----------------------+----------------------+

isLeafConfiguration pathReturns 0 if
specified node is a
leaf node, 1
otherwise

+----------------------+----------------------+----------------------+

getNodeTypeConfiguration pathReturns on of the
following: value
for value nodes,
leaf for leaf
nodes, multi for
multi nodes, tag
for tag nodes,
non-leaf for the
rest.

+----------------------+----------------------+----------------------+

listNodesConfiguration pathReturns list of
nodes under
specified
configuration
path[^5].

+----------------------+----------------------+----------------------+

listActiveNodesConfiguration pathReturns list of
nodes under
specified
configuration path
that are present in
currently used
config.

+----------------------+----------------------+----------------------+

listEffectiveNodesConfiguration pathReturns list of
effective nodes
under specified
configuration path
that are present in
effective config.

+----------------------+----------------------+----------------------+

returnValueConfiguration pathReturns value of a
node under specified
configuration path.

+----------------------+----------------------+----------------------+

returnActiveValueConfiguration pathReturns value of a
node under specified
configuration path
as present in
currently used
config.

+----------------------+----------------------+----------------------+

returnEffectiveValueConfiguration pathReturns effective
value of a node
under specified
configuration path
as present in
currently used
config.

+----------------------+----------------------+----------------------+

returnValuesConfiguration pathReturns values of a
multinode under
specified
configuration
path[^6].

+----------------------+----------------------+----------------------+

returnActiveValuesConfiguration pathReturns values of a
multinode under
specified
configuration path
as present in
currently used
config.

+----------------------+----------------------+----------------------+

rConfiguration pathReturns effective
eturnEffectiveValuesvalues of a
multinode under
specified
configuration path
as present in
currently used
config.

+----------------------+----------------------+----------------------+

validateTmplPathConfiguration pathValidate the path
regardless of given
value (e.g.
\"interfaces
ethernet\" is a
valid path whereas
\"interfaces
foobar\" is not.).
Returns 0 if path is
valid, 1 otherwise.

+----------------------+----------------------+----------------------+

validateTmplValPathConfiguration pathValidate
configuration path
with respect to
value (e.g.
\"interfaces
ethernet\" is a
valid path, whereas
\"interfaces foo\"
is not). Returns 0
if path is valid, 1
otherwise.

+----------------------+----------------------+----------------------+

validateTmplValPathConfiguration pathValidate
configuration path
with respect to
value (e.g.
\"interfaces
ethernet eth0\" is a
valid path, whereas
\"interfaces
ethernet foo0\" is
not). Returns 0 if
path is valid, 1
otherwise.

+----------------------+----------------------+----------------------+

showCfgConfiguration pathShows configuration
(may be empty)under specified
path.

+----------------------+----------------------+----------------------+

showConfigConfiguration pathShow configuration
(may be empty)under specified
path. Supports the
following options:\
\--show-active-only
--- show active
configuration\
\--show-working-only
--- show working
configuration\
\
--show-show-defaults
--- include default
value\
\--show-hide-secrets
--- replace private
information like
passwords with
\"\*\"\
\--show-context-diff
--- show \"context
diff\" between two
configs\
\--show-commands ---
show output in
\"commands\"\
\--show-ignore-edit
--- don\'t use the
edit level in
environment\
\--show-cfg1
<cfg1>{=html}
\--show-cfg2
<cfg2>{=html} ---
specify the two
configs to be diffed
(must specify both),
values may be file
names, \"\@ACTIVE\"
or \"\@WORKING\"

+----------------------+----------------------+----------------------+

loadFilePath to config fileLoad configuration
file

+----------------------+----------------------+----------------------+

getPreCommitHookDirNoneReturns path to
pre-commit hooks
directory

+----------------------+----------------------+----------------------+

getPostCommitHookDirNoneReturns path to
post-commit hooks
directory

+----------------------+----------------------+----------------------+

cfExistsPath to config file,Returns 0 if
configuration pathspecified
configuration path
exists in specified
config file

+----------------------+----------------------+----------------------+

cfReturnValuePath to config file,Returns value of
configuration pathspecified node in
specified file

+----------------------+----------------------+----------------------+

cfReturnValuesPath to config file,Returns values under
configuration pathspecified path in
specified file

+----------------------+----------------------+----------------------+

Usage

Setting up the session {#setting_up_the_session}

Before changing configuration and using most part of cli-shell-api
methods you must set up session. Current best practice is to use process
identifier (\$PPID) as session identifier.

  1. Obtain session environment session_env=$($SHELL_API getSessionEnv $PPID)
  2. Evaluate environment string eval $session_env
  3. Setup the session cli-shell-api setupSession

Then you can make sure session is set up:

cli-shell-api inSession
if [ $? -ne 0 ]; then
  echo "Something went wrong!"
fi

Don\'t forget to finish your session using cli-shell-api
teardownSession. In a bash script make sure session is finished using
something like:

function atexit() {
    cli-shell-api teardownSession
}
trap atexit EXIT

Configuration output {#configuration_output}

You can do configuration output even if session is not set up. Example:

  1. cli-shell-api showCfg firewall name TEST rule 10 action reject source { address 172.16.0.0/24 }

Working with multinode output {#working_with_multinode_output}

To work with output of listNodes, returnValues or similar methods you
must eval it. Example:

node_list=$(cli-shell-api listNodes firewall name TEST)
eval "NODES=($node_list)"

for i in "${NODES[@]}";
  do
    cli-shell-api showCfg firewall name TEST rule $i
  done

Modifying configuration {#modifying_configuration}

Warning: You must set up a session before modifying configuration.

cli-shell-api itself does not have methods to modify configuration. It
is done with separate commands that are in /opt/vyatta/sbin
(\${vyatta\_sbindir}) and have names same to configuration mode commands
with \"my\_\" prefix. The only exception is command for saving
configuration, which is /opt/vyatta/vyatta-save-config.pl (accepts
config file name as its optional argument).

You may use the following snippet:

SET=${vyatta_sbindir}/my_set

DELETE=${vyatta_sbindir}/my_delete

COPY=${vyatta_sbindir}/my_copy

MOVE=${vyatta_sbindir}/my_move

RENAME=${vyatta_sbindir}/my_rename

ACTIVATE=${vyatta_sbindir}/my_activate

DEACTIVATE=${vyatta_sbindir}/my_activate

COMMENT=${vyatta_sbindir}/my_comment

COMMIT=${vyatta_sbindir}/my_commit

DISCARD=${vyatta_sbindir}/my_discard

SAVE=${vyatta_sbindir}/vyatta-save-config.pl

Example:

$SET interfaces ethernet eth0 address 10.0.0.1/24
$COMMIT

Script examples {#script_examples}

  • [Search for nodes containing some string](Search_for_nodes_containing_some_string "wikilink").

References

{=html}
<references />
{=mediawiki}
{{Lowercase title}}

[Category: Development](Category:_Development "wikilink")

[^1]: This and all other methods that return environment variables

return a string suitable for \"eval\".

[^2]: This and other listNodes\* methods return strings that must be

eval\'ed into an array (e.g. values=\$(cli-shell-api listNodes
interfaces); eval \"nodes=(\$values)\" )

[^3]: Output of this and all other returnValues\* methods is a string

that must be eval\'ed.

[^4]: This and all other methods that return environment variables

return a string suitable for \"eval\".

[^5]: This and other listNodes\* methods return strings that must be

eval\'ed into an array (e.g. values=\$(cli-shell-api listNodes
interfaces); eval \"nodes=(\$values)\" )

[^6]: Output of this and all other returnValues\* methods is a string

that must be eval\'ed.
Last Author
s.lorente
Last Edited
Apr 19 2020, 9:24 PM