Page MenuHomeVyOS Platform

CLI Shell API
Updated 103 Days AgoPublic

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.

Definitions

Active config is config, currently used by system.

Working config is config we are making during configuration session.

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

It is invoked in format:

cli-shell-api <method> <configuration path>

Currently API has the following methods:

MethodArgumentsPurpose
getSessionEnvSession identifierReturns environment variables needed for configuration session to work[1]
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 and component (e.g. "set service" or "edit firewall")Returns environment variables needed for command completion 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[2].
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[3].
returnActiveValuesConfiguration pathReturns values of a multinode under specified configuration path as present in currently used config.
returnEffectiveValuesConfiguration pathReturns effective values 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 path (may be empty)Shows configuration under specified path.
showConfigConfiguration path (may be empty)Show configuration under specified path. Supports the following 8 options: 1: --show-active-only --> show active configuration; 2: --show-working-only --> show working configuration; 3: --show-show-defaults --> include default value; 4: --show-hide-secrets --> replace private information like passwords with "*"; 5: --show-context-diff --> show "context diff" between two configs; 6: --show-commands --> show output in "commands"; 7: --show-ignore-edit --> don't use the edit level in environment; 8: --show-cfg1 <cfg1> --show-cfg2 <cfg2> --> 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, configuration pathReturns 0 if specified configuration path exists in specified config file
cfReturnValuePath to config file, configuration pathReturns value of specified node in specified file
cfReturnValuesPath to config file, configuration pathReturns values under specified path in specified file

Usage

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.

# Obtain session environment
session_env=$($SHELL_API getSessionEnv $PPID)

# Evaluate environment string
eval $session_env

# 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

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

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

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

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

References

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

Last Author
s.lorente
Last Edited
Apr 21 2020, 12:28 PM

Event Timeline

s.lorente deleted this document.Apr 19 2020, 9:24 PM
s.lorente created this object.
s.lorente edited the content of this document. (Show Details)Apr 21 2020, 12:28 PM