Cli-shell-api

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

= 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

Currently API has the following methods:

= 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. session_env=$($SHELL_API getSessionEnv $PPID)
 * 1) Obtain session environment

eval $session_env
 * 1) Evaluate environment string

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
 * 1) Setup the session

Configuration output
You can do configuration output even if session is not set up. Example: action reject source { address 172.16.0.0/24 }
 * 1) cli-shell-api showCfg firewall name TEST rule 10

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_sbin_dir}) 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

 * Search for nodes containing some string.

= References =