Version 1 vs 3
Version 1 vs 3
Edits
Edits
- Edit by Unknown Object (User), Version 3
- Apr 21 2020 12:28 PM
- Edit by Unknown Object (User), Version 1
- Apr 19 2020 9:24 PM
Edit Older Version 1... | Edit Current Version 3... |
Content Changes
Content Changes
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:
+----------------------+----------------------+----------------------+
| Method | Arguments | Purpose |
+======================+======================+======================+
| getSessionEnv | Session identifier | Returns environment |
| | | variables needed for |
| | | configuration |
| | | session to work[^4] |
+----------------------+----------------------+----------------------+
| getEditEnv | Configuration path | Returns environment |
| | | variables for edit |
| | | level specified in |
| | | argument. |
+----------------------+----------------------+----------------------+
| getEditUpEnv | None | Returns environment |
| | | variables for edit |
| | | level above current |
| | | edit level. Returns |
| | | string \"Already at |
| | | the top level\" when |
| | | ran at the top edit |
| | | level. |
+----------------------+----------------------+----------------------+
| getEditResetEnv | None | Returns environment |
| | | variables for the |
| | | top level. |
+----------------------+----------------------+----------------------+
| editLevelAtRoot | None | Returns 0 if current |
| | | edit level is top |
| | | level, 1 otherwise |
+----------------------+----------------------+----------------------+
| getCompletionEnv | Command and | Returns environment |
| | component (e.g. | variables needed for |
| | \"set service\" or | command completion |
| | \"edit firewall\") | to work. |
+----------------------+----------------------+----------------------+
| getEditLevelStr | None | Returns current edit |
| | | level. |
+----------------------+----------------------+----------------------+
| markSessionUnsaved | None | Mark current |
| | | configuration |
| | | session unsaved. |
+----------------------+----------------------+----------------------+
| unmarkSessionUnsaved | None | Reset session |
| | | unsaved flag. |
+----------------------+----------------------+----------------------+
| sessionUnsaved | None | Returns 0 when |
| | | session unsaved flag |
| | | is set, 1 otherwise. |
+----------------------+----------------------+----------------------+
| setupSession | None | Initiate a |
| | | configuration |
| | | session. Needs |
| | | environment to be |
| | | set properly, see |
| | | getSessionEnv. |
+----------------------+----------------------+----------------------+
| sessionChanged | None | Returns 0 if |
| | | configuration was |
| | | changed from current |
| | | session, 1 |
| | | otherwise. |
+----------------------+----------------------+----------------------+
| teardownSession | None | End current |
| | | configuration |
| | | session. |
+----------------------+----------------------+----------------------+
| inSession | None | Returns 0 if |
| | | configuration |
| | | session is set up, 1 |
| | | otheriwise. |
+----------------------+----------------------+----------------------+
| exists | Configuration path | Returns 0 if |
| | | specified |
| | | configuration path |
| | | exists (either in |
| | | currently used or |
| | | built during the |
| | | session config), 1 |
| | | otherwise. |
+----------------------+----------------------+----------------------+
| existsActive | Configuration path | Returns 0 if |
| | | specified node |
| | | exists in the |
| | | current active |
| | | (running) |
| | | configuration, 1 |
| | | otherwise. |
+----------------------+----------------------+----------------------+
| existsEffective | Configuration path | Returns 0 if |
| | | specified path |
| | | exists in effective |
| | | config, 1 otherwise |
+----------------------+----------------------+----------------------+
| isMulti | Configuration path | Returns 0 if |
| | | specified node is a |
| | | multi node (i.e. may |
| | | have more than one |
| | | value), 1 otherwise |
+----------------------+----------------------+----------------------+
| isTag | Configuration path | Returns 0 if |
| | | specified node is a |
| | | tag node, 1 |
| | | otherwise |
+----------------------+----------------------+----------------------+
| Configuration path | ??? | |
+----------------------+----------------------+----------------------+
| isLeaf | Configuration path | Returns 0 if |
| | | specified node is a |
| | | leaf node, 1 |
| | | otherwise |
+----------------------+----------------------+----------------------+
| getNodeType | Configuration path | Returns 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. |
+----------------------+----------------------+----------------------+
| listNodes | Configuration path | Returns list of |
| | | nodes under |
| | | specified |
| | | configuration |
| | | path[^5]. |
+----------------------+----------------------+----------------------+
| listActiveNodes | Configuration path | Returns list of |
| | | nodes under |
| | | specified |
| | | configuration path |
| | | that are present in |
| | | currently used |
| | | config. |
+----------------------+----------------------+----------------------+
| listEffectiveNodes | Configuration path | Returns list of |
| | | effective nodes |
| | | under specified |
| | | configuration path |
| | | that are present in |
| | | effective config. |
+----------------------+----------------------+----------------------+
| returnValue | Configuration path | Returns value of a |
| | | node under specified |
| | | configuration path. |
+----------------------+----------------------+----------------------+
| returnActiveValue | Configuration path | Returns value of a |
| | | node under specified |
| | | configuration path |
| | | as present in |
| | | currently used |
| | | config. |
+----------------------+----------------------+----------------------+
| returnEffectiveValue | Configuration path | Returns effective |
| | | value of a node |
| | | under specified |
| | | configuration path |
| | | as present in |
| | | currently used |
| | | config. |
+----------------------+----------------------+----------------------+
| returnValues | Configuration path | Returns values of a |
| | | multinode under |
| | | specified |
| | | configuration |
| | | path[^6]. |
+----------------------+----------------------+----------------------+
| returnActiveValues | Configuration path | Returns values of a |
| | | multinode under |
| | | specified |
| | | configuration path |
| | | as present in |
| | | currently used |
| | | config. |
+----------------------+----------------------+----------------------+
| r | Configuration path | Returns effective |
| eturnEffectiveValues | | values of a |
| | | multinode under |
| | | specified |
| | | configuration path |
| | | as present in |
| | | currently used |
| | | config. |
+----------------------+----------------------+----------------------+
| validateTmplPath | Configuration path | Validate 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. |
+----------------------+----------------------+----------------------+
| validateTmplValPath | Configuration path | Validate |
| | | 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. |
+----------------------+----------------------+----------------------+
| validateTmplValPath | Configuration path | Validate |
| | | 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. |
+----------------------+----------------------+----------------------+
| showCfg | Configuration path | Shows configuration |
| | (may be empty) | under specified |
| | | path. |
+----------------------+----------------------+----------------------+
| showConfig | Configuration path | Show 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\" |
+----------------------+----------------------+----------------------+
| loadFile | Path to config file | Load configuration |
| | | file |
+----------------------+----------------------+----------------------+
| getPreCommitHookDir | None | Returns path to |
| | | pre-commit hooks |
| | | directory |
+----------------------+----------------------+----------------------+
| getPostCommitHookDir | None | Returns path to |
| | | post-commit hooks |
| | | directory |
+----------------------+----------------------+----------------------+
| cfExists | Path to config file, | Returns 0 if |
| | configuration path | specified |
| | | configuration path |
| | | exists in specified |
| | | config file |
+----------------------+----------------------+----------------------+
| cfReturnValue | Path to config file, | Returns value of |
| | configuration path | specified node in |
| | | specified file |
+----------------------+----------------------+----------------------+
| cfReturnValues | Path to config file, | Returns values under |
| | configuration path | specified 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.
# 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 {#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 {#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.
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:
| Method | Arguments | Purpose |
|-----------------------|-------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| getSessionEnv | Session identifier | Returns environment variables needed for configuration session to work[1] |
| getEditEnv | Configuration path | Returns environment variables for edit level specified in argument. |
| getEditUpEnv | None | Returns environment variables for edit level above current edit level. Returns string "Already at the top level" when ran at the top edit level. |
| getEditResetEnv | None | Returns environment variables for the top level. |
| editLevelAtRoot | None | Returns 0 if current edit level is top level, 1 otherwise |
| getCompletionEnv | Command and component (e.g. "set service" or "edit firewall") | Returns environment variables needed for command completion to work. |
| getEditLevelStr | None | Returns current edit level. |
| markSessionUnsaved | None | Mark current configuration session unsaved. |
| unmarkSessionUnsaved | None | Reset session unsaved flag. |
| sessionUnsaved | None | Returns 0 when session unsaved flag is set, 1 otherwise. |
| setupSession | None | Initiate a configuration session. Needs environment to be set properly, see getSessionEnv. |
| sessionChanged | None | Returns 0 if configuration was changed from current session, 1 otherwise. |
| teardownSession | None | End current configuration session. |
| inSession | None | Returns 0 if configuration session is set up, 1 otheriwise. |
| exists | Configuration path | Returns 0 if specified configuration path exists (either in currently used or built during the session config), 1 otherwise. |
| existsActive | Configuration path | Returns 0 if specified node exists in the current active (running) configuration, 1 otherwise. |
| existsEffective | Configuration path | Returns 0 if specified path exists in effective config, 1 otherwise |
| isMulti | Configuration path | Returns 0 if specified node is a multi node (i.e. may have more than one value), 1 otherwise |
| isTag | Configuration path | Returns 0 if specified node is a tag node, 1 otherwise |
| Configuration path | ??? | |
| isLeaf | Configuration path | Returns 0 if specified node is a leaf node, 1 otherwise |
| getNodeType | Configuration path | Returns 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. |
| listNodes | Configuration path | Returns list of nodes under specified configuration path[2]. |
| listActiveNodes | Configuration path | Returns list of nodes under specified configuration path that are present in currently used config. |
| listEffectiveNodes | Configuration path | Returns list of effective nodes under specified configuration path that are present in effective config. |
| returnValue | Configuration path | Returns value of a node under specified configuration path. |
| returnActiveValue | Configuration path | Returns value of a node under specified configuration path as present in currently used config. |
| returnEffectiveValue | Configuration path | Returns effective value of a node under specified configuration path as present in currently used config. |
| returnValues | Configuration path | Returns values of a multinode under specified configuration path[3]. |
| returnActiveValues | Configuration path | Returns values of a multinode under specified configuration path as present in currently used config. |
| returnEffectiveValues | Configuration path | Returns effective values of a multinode under specified configuration path as present in currently used config. |
| validateTmplPath | Configuration path | Validate 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. |
| validateTmplValPath | Configuration path | Validate 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. |
| validateTmplValPath | Configuration path | Validate 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. |
| showCfg | Configuration path (may be empty) | Shows configuration under specified path. |
| showConfig | Configuration 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" |
| loadFile | Path to config file | Load configuration file |
| getPreCommitHookDir | None | Returns path to pre-commit hooks directory |
| getPostCommitHookDir | None | Returns path to post-commit hooks directory |
| cfExists | Path to config file, configuration path | Returns 0 if specified configuration path exists in specified config file |
| cfReturnValue | Path to config file, configuration path | Returns value of specified node in specified file |
| cfReturnValues | Path to config file, configuration path | Returns 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.
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
at **/bin/cli-shell-api**. This page describes methods of the API as of
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, Inin such cases the effective config is the same as the running config.
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 \ 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.
committed, i.e., \"commit\" has successfully processed the- active && !working && !committed
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\ 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:
+----------------------+----------------------+----------------------+| Method | Arguments | Purpose |
| Method | Arguments | Purpose -----------------------|-------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+======================+======================+======================+| getSessionEnv | Session identifier | Returns environment variables needed for configuration session to work[1] |
| getSessionEnv | Session identifier | Returns environmentEditEnv | Configuration path | Returns environment variables for edit level specified in argument. |
| | | variables needed forgetEditUpEnv | None | Returns environment variables for edit level above current edit level. Returns string "Already at the top level" when ran at the top edit level. |
| | | configurationgetEditResetEnv | None | Returns environment variables for the top level. |
| | | session to work[^4]editLevelAtRoot | None | Returns 0 if current edit level is top level, 1 otherwise |
+----------------------+----------------------+----------------------+| getCompletionEnv | Command and component (e.g. "set service" or "edit firewall") | Returns environment variables needed for command completion to work. |
| getEditEnv | Configuration path | Returns environmentLevelStr | None | Returns current edit level. |
| | | variables for editmarkSessionUnsaved | None | Mark current configuration session unsaved. |
| | | level specified inunmarkSessionUnsaved | None | Reset session unsaved flag. |
| | | argument.sessionUnsaved | None | Returns 0 when session unsaved flag is set, 1 otherwise. |
+----------------------+----------------------+----------------------+| setupSession | None | Initiate a configuration session. Needs environment to be set properly, see getSessionEnv. |
| getEditUpEnv | None | Returns environmentsessionChanged | None | Returns 0 if configuration was changed from current session, 1 otherwise. |
| | | variables for editteardownSession | None | End current configuration session. |
| | | level above currentinSession | None | Returns 0 if configuration session is set up, 1 otheriwise. |
| | | edit level.exists | Configuration path | Returns 0 if specified configuration path exists (either in currently used or built during the session config), Returns1 otherwise. |
| | | string \"Already atexistsActive | Configuration path | Returns 0 if specified node exists in the current active (running) configuration, 1 otherwise. |
| | | the top level\" whenexistsEffective | Configuration path | Returns 0 if specified path exists in effective config, 1 otherwise |
| | | ran at the top editisMulti | Configuration path | Returns 0 if specified node is a multi node (i.e. may have more than one value), 1 otherwise |
| | | level.isTag | Configuration path | Returns 0 if specified node is a tag node, 1 otherwise |
+----------------------+----------------------+----------------------+| Configuration path | ??? | |
| getEditResetEnv | None | Returns environmentisLeaf | Configuration path | Returns 0 if specified node is a leaf node, 1 otherwise |
| | | variables for thegetNodeType | Configuration path | Returns 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. |
| | | top level.listNodes | Configuration path | Returns list of nodes under specified configuration path[2]. |
+----------------------+----------------------+----------------------+| listActiveNodes | Configuration path | Returns list of nodes under specified configuration path that are present in currently used config. |
| editLevelAtRoot | None | Returns 0 if currentlistEffectiveNodes | Configuration path | Returns list of effective nodes under specified configuration path that are present in effective config. |
| | | edit level is topreturnValue | Configuration path | Returns value of a node under specified configuration path. |
| | | level, 1 otherwisereturnActiveValue | Configuration path | Returns value of a node under specified configuration path as present in currently used config. |
+----------------------+----------------------+----------------------+| returnEffectiveValue | Configuration path | Returns effective value of a node under specified configuration path as present in currently used config. |
| getCompletionEnv | Command and | Returns environmentreturnValues | Configuration path | Returns values of a multinode under specified configuration path[3]. |
| | component (e.g. | variables needed forreturnActiveValues | Configuration path | Returns values of a multinode under specified configuration path as present in currently used config. |
| | \"set service\" or | command completionreturnEffectiveValues | Configuration path | Returns effective values of a multinode under specified configuration path as present in currently used config. |
| | \"edit firewall\") | to work.validateTmplPath | Configuration path | Validate 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. |
+----------------------+----------------------+----------------------+| validateTmplValPath | Configuration path | Validate 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. |
| getEditLevelStr | None | Returns current editvalidateTmplValPath | Configuration path | Validate 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. |
| | | level.showCfg | Configuration path (may be empty) | Shows configuration under specified path. |
+----------------------+----------------------+----------------------+| showConfig | Configuration 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" |
| markSessionUnsaved | None | Mark currentloadFile | Path to config file | Load configuration file |
| | | configurationgetPreCommitHookDir | None | Returns path to pre-commit hooks directory |
| | | session unsaved.getPostCommitHookDir | None | Returns path to post-commit hooks directory |
+----------------------+----------------------+----------------------+| cfExists | Path to config file, configuration path | Returns 0 if specified configuration path exists in specified config file |
| unmarkSessionUnsaved | None | Reset sessioncfReturnValue | Path to config file, configuration path | Returns value of specified node in specified file |
| | | unsaved flag. |
+----------------------+----------------------+----------------------+
| sessionUnsaved | None | Returns 0 when |
| | | session unsaved flag |
| | | is set, 1 otherwise. |
+----------------------+----------------------+----------------------+
| setupSession | None | Initiate a |
| | | configuration |
| | | session. Needs |
| | | environment to be |
| | | set properly, see |
| | | getSessionEnv. |
+----------------------+----------------------+----------------------+
| sessionChanged | None | Returns 0 if |
| | | configuration was |
| | | changed from current |
| | | session, 1 |
| | | otherwise. |
+----------------------+----------------------+----------------------+
| teardownSession | None | End current |
| | | configuration |
| | | session. |
+----------------------+----------------------+----------------------+
| inSession | None | Returns 0 if |
| | | configuration |
| | | session is set up, 1 |
| | | otheriwise. |
+----------------------+----------------------+----------------------+
| exists | Configuration path | Returns 0 if |
| | | specified |
| | | configuration path |
| | | exists (either in |
| | | currently used or |
| | | built during the |
| | | session config), 1 |
| | | otherwise. |
+----------------------+----------------------+----------------------+
| existsActive | Configuration path | Returns 0 if |
| | | specified node |
| | | exists in the |
| | | current active |
| | | (running) |
| | | configuration, 1 |
| | | otherwise. |
+----------------------+----------------------+----------------------+
| existsEffective | Configuration path | Returns 0 if |
| | | specified path |
| | | exists in effective |
| | | config, 1 otherwise |
+----------------------+----------------------+----------------------+
| isMulti | Configuration path | Returns 0 if |
| | | specified node is a |
| | | multi node (i.e. may |
| | | have more than one |
| | | value), 1 otherwise |
+----------------------+----------------------+----------------------+
| isTag | Configuration path | Returns 0 if |
| | | specified node is a |
| | | tag node, 1 |
| | | otherwise |
+----------------------+----------------------+----------------------+
| Configuration path | ??? | |
+----------------------+----------------------+----------------------+
| isLeaf | Configuration path | Returns 0 if |
| | | specified node is a |
| | | leaf node, 1 |
| | | otherwise |
+----------------------+----------------------+----------------------+
| getNodeType | Configuration path | Returns 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. |
+----------------------+----------------------+----------------------+
| listNodes | Configuration path | Returns list of |
| | | nodes under |
| | | specified |
| | | configuration |
| | | path[^5]. |
+----------------------+----------------------+----------------------+
| listActiveNodes | Configuration path | Returns list of |
| | | nodes under |
| | | specified |
| | | configuration path |
| | | that are present in |
| | | currently used |
| | | config. |
+----------------------+----------------------+----------------------+
| listEffectiveNodes | Configuration path | Returns list of |
| | | effective nodes |
| | | under specified |
| | | configuration path |
| | | that are present in |
| | | effective config. |
+----------------------+----------------------+----------------------+
| returnValue | Configuration path | Returns value of a |
| | | node under specified |
| | | configuration path. |
+----------------------+----------------------+----------------------+
| returnActiveValue | Configuration path | Returns value of a |
| | | node under specified |
| | | configuration path |
| | | as present in |
| | | currently used |
| | | config. |
+----------------------+----------------------+----------------------+
| returnEffectiveValue | Configuration path | Returns effective |
| | | value of a node |
| | | under specified |
| | | configuration path |
| | | as present in |
| | | currently used |
| | | config. |
+----------------------+----------------------+----------------------+
| returnValues | Configuration path | Returns values of a |
| | | multinode under |
| | | specified |
| | | configuration |
| | | path[^6]. |
+----------------------+----------------------+----------------------+
| returnActiveValues | Configuration path | Returns values of a |
| | | multinode under |
| | | specified |
| | | configuration path |
| | | as present in |
| | | currently used |
| | | config. |
+----------------------+----------------------+----------------------+
| r | Configuration path | Returns effective |
| eturnEffectiveValues | | values of a |
| | | multinode under |
| | | specified |
| | | configuration path |
| | | as present in |
| | | currently used |
| | | config. |
+----------------------+----------------------+----------------------+
| validateTmplPath | Configuration path | Validate 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. |
+----------------------+----------------------+----------------------+
| validateTmplValPath | Configuration path | Validate |
| | | 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. |
+----------------------+----------------------+----------------------+
| validateTmplValPath | Configuration path | Validate |
| | | 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. |
+----------------------+----------------------+----------------------+
| showCfg | Configuration path | Shows configuration |
| | (may be empty) | under specified |
| | | path. |
+----------------------+----------------------+----------------------+
| showConfig | Configuration path | Show 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\" |
+----------------------+----------------------+----------------------+
| loadFile | Path to config file | Load configuration |
| | | file |
+----------------------+----------------------+----------------------+
| getPreCommitHookDir | None | Returns path to |
| | | pre-commit hooks |
| | | directory |
+----------------------+----------------------+----------------------+
| getPostCommitHookDir | None | Returns path to |
| | | post-commit hooks |
| | | directory |
+----------------------+----------------------+----------------------+
| cfExists | Path to config file, | Returns 0 if |
| | configuration path | specified |
| | | configuration path |
| | | exists in specified |
| | | config file |
+----------------------+----------------------+----------------------+
| cfReturnValue | Path to config file, | Returns value of |
| | configuration path | specified node in |
| | | specified file |
+----------------------+----------------------+----------------------+
| cfReturnValues | Path to config file, | Returns values under |
| | configuration path | specified path in |
| | | specified file |
+----------------------+----------------------+----------------------+| cfReturnValues | Path to config file, configuration path | Returns values under specified 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.
```
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 {#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 {#working_with_multinode_output}
-----------------------------```
To workWorking with output of listNodes, returnValues or similar methods you
must eval it. Example: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
It is done with separate commands that are in /opt/vyatta/sbin
(\ (${vyatta\_sbindir}) and have names same to configuration mode commands
with \"my\_\"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".
[^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)" )
[^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\* methods is a string that must be eval'ed.