Version 1 vs 7
Version 1 vs 7
Edits
Edits
- Edit by Unknown Object (User), Version 7
- Apr 19 2020 11:21 PM
- Edit by Unknown Object (User), Version 1
- Apr 14 2020 10:03 PM
Edit Older Version 1... | Edit Current Version 7... |
Content Changes
Content Changes
<p>Vyatta::Config (/opt/vyatta/share/perl5/Vyatta/Config.pm) is a Perl API library for working with VyOS configuration (and Vyatta and EdgeOS too).</p>
<h1 id="using_the_library">Using the Library</h1>
<pre><code>use lib '/opt/vyatta/share/perl5';
use Vyatta::Config;
$config = new Vyatta::Config;</code></pre>
<h1 id="definitions">Definitions</h1>
<p><strong>Active config</strong> is config, currently used by system.</p>
<p><strong>Working config</strong> is config we are making during configuration session.</p>
<h2 id="effective_config">Effective config</h2>
<p>The definition of "effective" is different under these two scenarios.</p>
<ol>
<li>When used outside a config session, "effective" == "active". In other words, in such cases the effective config is the same as the running config.</li>
<li>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.</li>
</ol>
<ul>
<li>active && working<br />
Path is in both active and working configs, i.e., unchanged.</li>
<li>!active && working && committed<br />
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.</li>
<li>active && !working && !committed<br />
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.</li>
</ul>
<p><strong>Note:</strong> 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.</p>
<h1 id="method_reference">Method reference</h1>
<p>Currently API has the following methods:</p>
<table>
<thead>
<tr class="header">
<th><p>Method</p></th>
<th><p>Arguments</p></th>
<th><p>Returns</p></th>
<th><p>Purpose</p></th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td><p>Low-level API functions that use the cstore library directly.</p></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr class="even">
<td><p>exists</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if specified node exists in current working config.</p></td>
</tr>
<tr class="odd">
<td><p>existsOrig</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if specified node exists in current active (running) config.</p></td>
</tr>
<tr class="even">
<td><p>isDefault</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if specified node has default value in current working config.</p></td>
</tr>
<tr class="odd">
<td><p>isDefaultOrig</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if specified node had default value in current active (running) config.</p></td>
</tr>
<tr class="even">
<td><p>listNodes</p></td>
<td><p>Configuration path</p></td>
<td><p>Array</p></td>
<td><p>Returns array of all child nodes under specified path in working config.</p></td>
</tr>
<tr class="odd">
<td><p>listOrigNodes</p></td>
<td><p>Configuration path</p></td>
<td><p>Array</p></td>
<td><p>Returns array of all child nodes under specified path in active config.</p></td>
</tr>
<tr class="even">
<td><p>returnValue</p></td>
<td><p>Configuration node</p></td>
<td><p>Scalar</p></td>
<td><p>Returns value of a node under specified path in working config.</p></td>
</tr>
<tr class="odd">
<td><p>returnOrigValue</p></td>
<td><p>Configuration node</p></td>
<td><p>Scalar</p></td>
<td><p>Returns value of a node under specified path in active config.</p></td>
</tr>
<tr class="even">
<td><p>returnValues</p></td>
<td><p>Configuration multi-value node</p></td>
<td><p>Array</p></td>
<td><p>Returns array of all values of a multi-value node under specified path in working config.</p></td>
</tr>
<tr class="odd">
<td><p>returnOrigValues</p></td>
<td><p>Configuration multi-value node</p></td>
<td><p>Array</p></td>
<td><p>Returns array of all values of a multi-value node under specified path in active config.</p></td>
</tr>
<tr class="even">
<td><p>Observers of the "effective" config</p></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr class="odd">
<td><p>isEffective</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if node under specified path is "effective".</p></td>
</tr>
<tr class="even">
<td><p>isActive</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Same to isEffective.</p></td>
</tr>
<tr class="odd">
<td><p>listEffectiveNodes</p></td>
<td><p>Configuration path</p></td>
<td><p>Aray</p></td>
<td><p>Returns array of "effective" child nodes during current commit under specified path.</p></td>
</tr>
<tr class="even">
<td><p>listOrigPlusComNodes</p></td>
<td><p>Configuration path</p></td>
<td><p>Array</p></td>
<td><p>Same to listEffectiveNodes.</p></td>
</tr>
<tr class="odd">
<td><p>returnEffectiveValue</p></td>
<td><p>Configuration node</p></td>
<td><p>Scalar</p></td>
<td><p>Returns "effective" value of a node during current commit.</p></td>
</tr>
<tr class="even">
<td><p>returnOrigPlusComValue</p></td>
<td><p>Configuration node</p></td>
<td><p>Scalar</p></td>
<td><p>Returns "effective" value of a node during current commit.</p></td>
</tr>
<tr class="odd">
<td><p>returnEffectiveValues</p></td>
<td><p>Configuraion multi-value node</p></td>
<td><p>Array</p></td>
<td><p>Returns array of "effective" values of a multi-value node during current commit.</p></td>
</tr>
<tr class="even">
<td><p>returnOrigPlusComValues</p></td>
<td><p>Configuraion multi-value node</p></td>
<td><p>Array</p></td>
<td><p>Returns array of "effective" values of a multi-value node during current commit.</p></td>
</tr>
<tr class="odd">
<td><p>isDeleted</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if node has been deleted in working config.</p></td>
</tr>
<tr class="even">
<td><p>listDeleted</p></td>
<td><p>Configuration path</p></td>
<td><p>Array</p></td>
<td><p>Returns array of nodes that have been deleted under specified level in working config.</p></td>
</tr>
<tr class="odd">
<td><p>returnDeletedValues</p></td>
<td><p>Configuration multi-value node</p></td>
<td><p>Array</p></td>
<td><p>Returns array of values of a multi-value node that have been deleted in working config.</p></td>
</tr>
<tr class="even">
<td><p>isAdded</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if specified node has been added in working config.</p></td>
</tr>
<tr class="odd">
<td><p>isChanged</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if specified node has been changed in working config.</p></td>
</tr>
<tr class="even">
<td><p>listNodeStatus</p></td>
<td><p>Configuration path</p></td>
<td><p>Hash</p></td>
<td><p>Return a hash of status of child nodes at specified level. Node name is the hash key. node status is the hash value. Node status can be one of "deleted", "added", "changed", or "static".</p></td>
</tr>
<tr class="odd">
<td><p>getTmplChildren</p></td>
<td><p>Configuration path</p></td>
<td><p>Array</p></td>
<td><p>Return list of child nodes in the template hierarchy at specified level.</p></td>
</tr>
<tr class="even">
<td><p>validateTmplPath</p></td>
<td><p>Configuration path</p></td>
<td><p>True or false</p></td>
<td><p>Return whether specified path is a valid template path.</p></td>
</tr>
<tr class="odd">
<td><p>parseTmplAll</p></td>
<td><p>Configuration path</p></td>
<td><p>Hash</p></td>
<td><p>Return hash ref of parsed template of specified path, undef if path is invalid. note: if !allow_val, path must terminate at a "node", not "value".</p></td>
</tr>
<tr class="even">
<td><p>hasTmplChildren</p></td>
<td><p>Configuration path</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if specified configuration path has child nodes.</p></td>
</tr>
<tr class="odd">
<td><p>"Deactivate-aware" observers of current working config or active config.</p></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr class="even">
<td><p>deactivated</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Return whether specified node is deactivated in working config. Note that this is different from "marked deactivated". If a node is "marked deactivated", then the node itself and any descendants are "deactivated".</p></td>
</tr>
<tr class="odd">
<td><p>deactivatedOrig</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Return whether specified node is deactivated in active config.</p></td>
</tr>
<tr class="even">
<td><p>returnValuesDA</p></td>
<td><p>Configuration multi-value node</p></td>
<td><p>Array</p></td>
<td><p>Deactivate aware version of returnValues().</p></td>
</tr>
<tr class="odd">
<td><p>returnOrigValuesDA</p></td>
<td><p>Configuration multi-value node</p></td>
<td><p>Array</p></td>
<td><p>DA version of returnOrigValues().</p></td>
</tr>
<tr class="even">
<td><p>returnValueDA</p></td>
<td><p>Configuration node</p></td>
<td><p>Scalar</p></td>
<td><p>DA version of returnOrigValue().</p></td>
</tr>
<tr class="odd">
<td><p>listOrigNodesDA</p></td>
<td><p>Configuration path</p></td>
<td><p>Array</p></td>
<td><p>DA version of listOrigNodes()</p></td>
</tr>
<tr class="even">
<td><p>listNodeStatusDA</p></td>
<td><p>Configuration path</p></td>
<td><p>Hash</p></td>
<td><p>DA version of listNodeStatus().</p></td>
</tr>
<tr class="odd">
<td><p>returnComment</p></td>
<td><p>Configuration node</p></td>
<td><p>Scalar</p></td>
<td><p>Returns comment of "node" in working config or undef if comment doesn't exist.</p></td>
</tr>
<tr class="even">
<td><p>returnOrigComment</p></td>
<td><p>Configuration node</p></td>
<td><p>Scalar</p></td>
<td><p>Returns comment of "node" in active config or undef if comment doesn't exist</p></td>
</tr>
<tr class="odd">
<td><p>High-level API functions (not using the cstore library directly)</p></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr class="even">
<td><p>setLevel</p></td>
<td><p>Configuration path</p></td>
<td><p>Current level</p></td>
<td><p>Set the current level of config hierarchy to specified level (if defined).</p></td>
</tr>
<tr class="odd">
<td><p>returnParent</p></td>
<td><p>Configuration node</p></td>
<td><p>Scalar</p></td>
<td><p>Returns the name of ancestor node relative to the current level. Each level up is represented by a ".." in the argument.</p></td>
</tr>
<tr class="even">
<td><p>parseTmpl</p></td>
<td><p>Configuration path</p></td>
<td><p>Array</p></td>
<td><p>Parse template of specified path and return ($is_multi, $is_text, $default) or undef if specified path is not valid.</p></td>
</tr>
<tr class="odd">
<td><p>isTagNode</p></td>
<td><p>Configuration path</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if specified path is a tag node.</p></td>
</tr>
<tr class="even">
<td><p>isLeafNode</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if specified path is a "leaf node", i.e., single-/multi-value node.</p></td>
</tr>
<tr class="odd">
<td><p>isLeafValue</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if specified path is a "leaf value", i.e., value of a leaf node.</p></td>
</tr>
<tr class="even">
<td><p>compareValueLists</p></td>
<td><p>Original value list and new value list</p></td>
<td><p>Lists of deleted and added nodes</p></td>
<td><p>Compare two value lists and return "deleted" and "added" lists. Since this is for multi-value nodes, there is no "changed" (if a value's ordering changed, it is deleted then added).</p></td>
</tr>
</tbody>
</table>
<h2 id="usage_example">Usage example</h2>
<p>Background: Your helpdesk guys ask you to make a spreadsheet with remote-access PPTP VPN user information and keep it up to date. Of course you do not want to copy and paste this information by hand.</p>
<p>All spreadsheet software supports import from CSV, so the only thing we need to do is to extract values from config and print then as comma separated lines, passwords enclosed into double quotes for the case they contain a comma and add some header. Like this:</p>
<p><code>user,password,address,is_disabled</code><br />
<code>johnsmith,"this,isapass",192.0.2.41,no</code></p>
<p>Here we go:</p>
<pre><code>#!/usr/bin/perl
use strict;
# using the Vyatta perl API
use lib "/opt/vyatta/share/perl5/";
use Vyatta::Config;
# Settings
my $proto = "pptp";
my $delimiter = ",";
# CSV RFC4180 requires to use CRLF (\r\n) as line break
my $header = "user,password,address,disabled\r\n";
# Create a config instance
my $config = new Vyatta::Config;
# Set default config level, this allows to use relative paths
$config->setLevel("vpn pptp remote-access authentication local-users username");
# Obtain array of user names
my @users = $config->listNodes();
# Print file header
print $header;
# Now walk through the user names, obtain values and print them
foreach my $user (@users) {
# Since we set config level to "vpn pptp remote-access authentication local-users username"
# we now can specify only the remaining part as methods argument,
# it will be appended to the path we used in setLevel()
my $password = $config->returnValue("$user password");
my $address = $config->returnValue("$user static-ip");
#"disable" is a leaf node with no value, so we should check
# if it exists instead of obtaining its value
my $disabled = $config->exists("$user disable") ? "yes" : "no";
# It's not prohibited to use "," in passwords,
# so we should enclose them into quotes to prevent
# the parser from treating them as delimiters
$password = "\"$password\"";
my $line = join($delimiter, $user, $password, $address, $disabled);
print "$line\r\n";
}</code></pre>
<p>Check it works:</p>
<pre><code>vyatta@R1# show vpn pptp remote-access authentication local-users
username joerandomuser {
disable
password qwerrty
static-ip 10.91.17.105
}
username johnsmith {
password this,isapass
}
vyatta@R1# perl ./pptpusers.pl
user,password,address,disabled
joerandomuser,"qwerrty",10.91.17.105,yes
johnsmith,"this,isapass",,no</code></pre>
<p><a href="Category:_Development" title="wikilink">Category: Development</a></p>
Vyatta::Config (/opt/vyatta/share/perl5/Vyatta/Config.pm) is a Perl API library for working with VyOS configuration (and Vyatta and EdgeOS too).
Deprecation warning
===============
Since VyOS 1.2.0, no new Perl code is accepted to the mainline VyOS. This documentation is kept for the reference since there's still old Perl code that needs bug fixes until it's replaced with new Python code.
Using the Library
=================
use lib '/opt/vyatta/share/perl5';
use Vyatta::Config;
$config = new Vyatta::Config;
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
================
Currently API has the following methods:
- **Low-level API functions that use the cstore library directly: **
| Method | Arguments | Returns | Purpose |
|----------------------------------------------------------------------------|----------------------------------------|----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
| exists | Configuration node | True or false | Returns true if specified node exists in current working config. |
| existsOrig | Configuration node | True or false | Returns true if specified node exists in current active (running) config. |
| isDefault | Configuration node | True or false | Returns true if specified node has default value in current working config. |
| isDefaultOrig | Configuration node | True or false | Returns true if specified node had default value in current active (running) config. |
| listNodes | Configuration path | Array | Returns array of all child nodes under specified path in working config. |
| listOrigNodes | Configuration path | Array | Returns array of all child nodes under specified path in active config. |
| returnValue | Configuration node | Scalar | Returns value of a node under specified path in working config. |
| returnOrigValue | Configuration node | Scalar | Returns value of a node under specified path in active config. |
| returnValues | Configuration multi-value node | Array | Returns array of all values of a multi-value node under specified path in working config. |
| returnOrigValues | Configuration multi-value node | Array | Returns array of all values of a multi-value node under specified path in active config. |
|
- **Observers of the "effective" config:**
| isEffective | Configuration node | True or false | Returns true if node under specified path is "effective". |
| isActive | Configuration node | True or false | Same to isEffective. |
| listEffectiveNodes | Configuration path | Aray | Returns array of "effective" child nodes during current commit under specified path. |
| listOrigPlusComNodes | Configuration path | Array | Same to listEffectiveNodes. |
| returnEffectiveValue | Configuration node | Scalar | Returns "effective" value of a node during current commit. |
| returnOrigPlusComValue | Configuration node | Scalar | Returns "effective" value of a node during current commit. |
| returnEffectiveValues | Configuraion multi-value node | Array | Returns array of "effective" values of a multi-value node during current commit. |
| returnOrigPlusComValues | Configuraion multi-value node | Array | Returns array of "effective" values of a multi-value node during current commit. |
| isDeleted | Configuration node | True or false | Returns true if node has been deleted in working config. |
| listDeleted | Configuration path | Array | Returns array of nodes that have been deleted under specified level in working config. |
| returnDeletedValues | Configuration multi-value node | Array | Returns array of values of a multi-value node that have been deleted in working config. |
| isAdded | Configuration node | True or false | Returns true if specified node has been added in working config. |
| isChanged | Configuration node | True or false | Returns true if specified node has been changed in working config. |
| listNodeStatus | Configuration path | Hash | Return a hash of status of child nodes at specified level. Node name is the hash key. node status is the hash value. Node status can be one of "deleted", "added", "changed", or "static". |
| getTmplChildren | Configuration path | Array | Return list of child nodes in the template hierarchy at specified level. |
| validateTmplPath | Configuration path | True or false | Return whether specified path is a valid template path. |
| parseTmplAll | Configuration path | Hash | Return hash ref of parsed template of specified path, undef if path is invalid. note: if !allow_val, path must terminate at a "node", not "value". |
| hasTmplChildren | Configuration path | True or false | Returns true if specified configuration path has child nodes. |
- **"Deactivate-aware" observers of current working config or active config;**
**Note: ** deactivate/activate commands are disabled in the CLI due to unsolvable problem in the configuration backends. These functions shouldn't be used.
| deactivated | Configuration node | True or false | Return whether specified node is deactivated in working config. Note that this is different from "marked deactivated". If a node is "marked deactivated", then the node itself and any descendants are "deactivated". |
| deactivatedOrig | Configuration node | True or false | Return whether specified node is deactivated in active config. |
| returnValuesDA | Configuration multi-value node | Array | Deactivate aware version of returnValues(). |
| returnOrigValuesDA | Configuration multi-value node | Array | DA version of returnOrigValues(). |
| returnValueDA | Configuration node | Scalar | DA version of returnOrigValue(). |
| listOrigNodesDA | Configuration path | Array | DA version of listOrigNodes() |
| listNodeStatusDA | Configuration path | Hash | DA version of listNodeStatus(). |
| returnComment | Configuration node | Scalar | Returns comment of "node" in working config or undef if comment doesn't exist. |
| returnOrigComment | Configuration node | Scalar | Returns comment of "node" in active config or undef if comment doesn't exist |
- **High-level API functions (not using the cstore library directly):**
| setLevel | Configuration path | Current level | Set the current level of config hierarchy to specified level (if defined). |
| returnParent | Configuration node | Scalar | Returns the name of ancestor node relative to the current level. Each level up is represented by a ".." in the argument. |
| parseTmpl | Configuration path | Array | Parse template of specified path and return ($is_multi, $is_text, $default) or undef if specified path is not valid. |
| isTagNode | Configuration path | True or false | Returns true if specified path is a tag node. |
| isLeafNode | Configuration node | True or false | Returns true if specified path is a "leaf node", i.e., single-/multi-value node. |
| isLeafValue | Configuration node | True or false | Returns true if specified path is a "leaf value", i.e., value of a leaf node. |
| compareValueLists | Original value list and new value list | Lists of deleted and added nodes | Compare two value lists and return "deleted" and "added" lists. Since this is for multi-value nodes, there is no "changed" (if a value's ordering changed, it is deleted then added). |
Usage example
-------------
Background: Your helpdesk guys ask you to make a spreadsheet with
remote-access PPTP VPN user information and keep it up to date. Of
course you do not want to copy and paste this information by hand.
All spreadsheet software supports import from CSV, so the only thing we
need to do is to extract values from config and print then as comma
separated lines, passwords enclosed into double quotes for the case they
contain a comma and add some header. Like this:
```
user,password,address,is_disabled
johnsmith,"this,isapass",192.0.2.41,no
```
Here we go:
#!/usr/bin/perl
use strict;
# using the Vyatta perl API
use lib "/opt/vyatta/share/perl5/";
use Vyatta::Config;
# Settings
my $proto = "pptp";
my $delimiter = ",";
# CSV RFC4180 requires to use CRLF (\r\n) as line break
my $header = "user,password,address,disabled\r\n";
# Create a config instance
my $config = new Vyatta::Config;
# Set default config level, this allows to use relative paths
$config->setLevel("vpn pptp remote-access authentication local-users username");
# Obtain array of user names
my @users = $config->listNodes();
# Print file header
print $header;
# Now walk through the user names, obtain values and print them
foreach my $user (@users) {
# Since we set config level to "vpn pptp remote-access authentication local-users username"
# we now can specify only the remaining part as methods argument,
# it will be appended to the path we used in setLevel()
my $password = $config->returnValue("$user password");
my $address = $config->returnValue("$user static-ip");
#"disable" is a leaf node with no value, so we should check
# if it exists instead of obtaining its value
my $disabled = $config->exists("$user disable") ? "yes" : "no";
# It's not prohibited to use "," in passwords,
# so we should enclose them into quotes to prevent
# the parser from treating them as delimiters
$password = "\"$password\"";
my $line = join($delimiter, $user, $password, $address, $disabled);
print "$line\r\n";
}
Check it works:
vyatta@R1# show vpn pptp remote-access authentication local-users
username joerandomuser {
disable
password qwerrty
static-ip 10.91.17.105
}
username johnsmith {
password this,isapass
}
vyatta@R1# perl ./pptpusers.pl
user,password,address,disabled
joerandomuser,"qwerrty",10.91.17.105,yes
johnsmith,"this,isapass",,no
<p>Vyatta::Config (/opt/vyatta/share/perl5/Vyatta/Config.pm) is a Perl API library for working with VyOS configuration (and Vyatta and EdgeOS too).</p>
Deprecation warning
<h1 id="using_the_library">Using the Library</h1>===============
Since VyOS 1.2.0, no new Perl code is accepted to the mainline VyOS. This documentation is kept for the reference since there's still old Perl code that needs bug fixes until it's replaced with new Python code.
Using the Library
<pre><code>=================
use lib ''/opt/vyatta/share/perl5';';
use Vyatta::Config;
$config = new Vyatta::Config;</code></pre>
Definitions
<h1 id="definitions">Definitions</h1>===========
**Active config** is config, currently used by system.
**Working config** is config we are making during configuration session.
Effective config
<p><strong>A----------------
The definition of "effective config</strong> is" is different under these two scenarios.
1. When used outside a config session, currently used by system.</p>"effective" == "active". In
<p><strong>Working config</strong> is config we are making during other words, in such cases the effective configuration session.</p> is the same as the
<h2 id="effective_config">Effective running config</h2>.
<p>The definition of "effective" is different under these two scenarios.</p>2. When used during a config session, a config path (leading to either
<ol> a "node" or a "value") is "effective" if ANY of the following
<li>When used outside a config session, "effective" == "active". In other words, in such cases the effective config is the same as the running config.</li> is true.
- active && working
<li>When used during a config session Path is in both active and working configs, a config path (leading to either a "node" or a "value") is "effective" if ANY of the following is true.</li>i.e., unchanged.
</ol>- !active && working && committed
<ul> Path is not in active, has been set in working, AND has already been
<li>active && committed, i.e., working<br />"commit" has successfully processed the
Path is in both active and working configs, i.e., unchanged.</li> addition/update of the path.
<li>!- active && & !working && & !committed<br />
Path is not in active, has been set in working, AND has already been committed Path is in active, i.e.has been deleted from working, "commit" has successfully processed the addition/update of the path.</li>AND has not been
<li>active && committed yet, !working &&i.e., !"committed<br />it" (per priority) has not processed the
Path is in active, has been deleted from working deletion of the path yet, ANDor it has not been committed yet, i.e.been processed but failed.
**Note:** during commit, "commit" (per priority)deactivate has not processed the deletion of the path yet,the same effect as delete. or it has been processed but failed.</li>So in
</ul>such cases, as far as these functions are concerned, deactivated nodes
<p><strong>Note:</strong> 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.</p>don't exist.
Method reference
<h1 id="method_reference">Method reference</h1>================
Currently API has the following methods:
- **Low-level API functions that use the cstore library directly: **
| Method | Arguments | Returns | Purpose |
<p>Currently API has the following methods:</p>|----------------------------------------------------------------------------|----------------------------------------|----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
<table>|
<thead>| exists | Configuration node | True or false | Returns true if specified node exists in current working config. |
<tr class="header">| existsOrig | Configuration node | True or false | Returns true if specified node exists in current active (running) config. |
<th><p>Method</p></th>| isDefault | Configuration node | True or false | Returns true if specified node has default value in current working config. |
<th><p>Arguments</p></th>| isDefaultOrig | Configuration node | True or false | Returns true if specified node had default value in current active (running) config. |
<th><p>Returns</p></th>| listNodes | Configuration path | Array | Returns array of all child nodes under specified path in working config. |
<th><p>Purpose</p></th>| listOrigNodes | Configuration path | Array | Returns array of all child nodes under specified path in active config. |
</tr>| returnValue | Configuration node | Scalar | Returns value of a node under specified path in working config. |
</thead>| returnOrigValue | Configuration node | Scalar | Returns value of a node under specified path in active config. |
<tbody>| returnValues | Configuration multi-value node | Array | Returns array of all values of a multi-value node under specified path in working config. |
<tr class="odd">| returnOrigValues | Configuration multi-value node | Array | Returns array of all values of a multi-value node under specified path in active config. |
<td><p>Low-level API functions that use the cstore library directly.</p></td> |
- **Observers of the "effective" config:**
| isEffective | Configuration node | True or false | Returns true if node under specified path is "effective". |
<td></td>| isActive | Configuration node | True or false | Same to isEffective. |
<td></td>| listEffectiveNodes | Configuration path | Aray | Returns array of "effective" child nodes during current commit under specified path. |
<td></td>| listOrigPlusComNodes | Configuration path | Array | Same to listEffectiveNodes. |
</tr>| returnEffectiveValue | Configuration node | Scalar | Returns "effective" value of a node during current commit. |
<tr class="even">| returnOrigPlusComValue | Configuration node | Scalar | Returns "effective" value of a node during current commit. |
<td><p>exists</p></td>| returnEffectiveValues | Configuraion multi-value node | Array | Returns array of "effective" values of a multi-value node during current commit. |
<td><p>Configuration node</p></td>| returnOrigPlusComValues | Configuraion multi-value node | Array | Returns array of "effective" values of a multi-value node during current commit. |
<td><p>True or false</p></td>| isDeleted | Configuration node | True or false | Returns true if node has been deleted in working config. |
<td><p>Returns true if specified node exists in current working config.</p></td>| listDeleted | Configuration path | Array | Returns array of nodes that have been deleted under specified level in working config. |
</tr>| returnDeletedValues | Configuration multi-value node | Array | Returns array of values of a multi-value node that have been deleted in working config. |
<tr class="odd">| isAdded | Configuration node | True or false | Returns true if specified node has been added in working config. |
<td><p>existsOrig</p></td>| isChanged | Configuration node | True or false | Returns true if specified node has been changed in working config. |
<td><p>Configuration node</p></td>| listNodeStatus | Configuration path | Hash | Return a hash of status of child nodes at specified level. Node name is the hash key. node status is the hash value. Node status can be one of "deleted", "added", "changed", or "static". |
<td><p>True or false</p></td>| getTmplChildren | Configuration path | Array | Return list of child nodes in the template hierarchy at specified level. |
<td><p>Returns true if specified node exists in current active (running) config.</p></td>| validateTmplPath | Configuration path | True or false | Return whether specified path is a valid template path. |
</tr>| parseTmplAll | Configuration path | Hash | Return hash ref of parsed template of specified path, undef if path is invalid. note: if !allow_val, path must terminate at a "node", not "value". |
<tr class="even">| hasTmplChildren | Configuration path | True or false | Returns true if specified configuration path has child nodes. |
- **"Deactivate-aware" observers of current working config or active config;**
**Note: ** deactivate/activate commands are disabled in the CLI due to unsolvable problem in the configuration backends. These functions shouldn't be used.
| deactivated | Configuration node | True or false | Return whether specified node is deactivated in working config. Note that this is different from "marked deactivated". If a node is "marked deactivated", then the node itself and any descendants are "deactivated". |
<td><p>isDefault</p></td>| deactivatedOrig | Configuration node | True or false | Return whether specified node is deactivated in active config. |
<td><p>Configuration node</p></td>| returnValuesDA | Configuration multi-value node | Array | Deactivate aware version of returnValues(). |
<td><p>True or false</p></td>| returnOrigValuesDA | Configuration multi-value node | Array | DA version of returnOrigValues(). |
<td><p>Returns true if specified node has default value in current working config.</p></td>| returnValueDA | Configuration node | Scalar | DA version of returnOrigValue(). |
</tr>| listOrigNodesDA | Configuration path | Array | DA version of listOrigNodes() |
<tr class="odd">| listNodeStatusDA | Configuration path | Hash | DA version of listNodeStatus(). |
<td><p>isDefaultOrig</p></td>| returnComment | Configuration node | Scalar | Returns comment of "node" in working config or undef if comment doesn't exist. |
<td><p>Configuration node</p></td>| returnOrigComment | Configuration node | Scalar | Returns comment of "node" in active config or undef if comment doesn't exist |
- **High-level API functions (not using the cstore library directly):**
| setLevel | Configuration path | Current level | Set the current level of config hierarchy to specified level (if defined). |
<td><p>True or false</p></td>| returnParent | Configuration node | Scalar | Returns the name of ancestor node relative to the current level. Each level up is represented by a ".." in the argument. |
<td><p>Returns true if specified node had default value in current active (running) config.</p></td>| parseTmpl | Configuration path | Array | Parse template of specified path and return ($is_multi, $is_text, $default) or undef if specified path is not valid. |
</tr>| isTagNode | Configuration path | True or false | Returns true if specified path is a tag node. |
<tr class="even">| isLeafNode | Configuration node | True or false | Returns true if specified path is a "leaf node", i.e., single-/multi-value node. |
<td><p>listNodes</p></td>| isLeafValue | Configuration node | True or false | Returns true if specified path is a "leaf value", i.e., value of a leaf node. |
<td><p>Configuration path</p></td>| compareValueLists | Original value list and new value list | Lists of deleted and added nodes | Compare two value lists and return "deleted" and "added" lists. Since this is for multi-value nodes, there is no "changed" (if a value's ordering changed, it is deleted then added). |
Usage example
<td><p>Array</p></td>-------------
Background: Your helpdesk guys ask you to make a spreadsheet with
<td><p>Returns array of all child nodes under specified path in working config.</p></td>remote-access PPTP VPN user information and keep it up to date. Of
</tr>course you do not want to copy and paste this information by hand.
All spreadsheet software supports import from CSV, so the only thing we
<tr class="odd">need to do is to extract values from config and print then as comma
<td><p>listOrigNodes</p></td>separated lines, passwords enclosed into double quotes for the case they
<td><p>Configuration path</p></td>contain a comma and add some header. Like this:
```
<td><p>Array</p></td>user,password,address,is_disabled
<td><p>Returns array of all child nodes under specified path in active config.</p></td>johnsmith,"this,isapass",192.0.2.41,no
</tr>
<tr class="even">
<td><p>returnValue</p></td>
<td><p>Configuration node</p></td>
<td><p>Scalar</p></td>
<td><p>Returns value of a node under specified path in working config.</p></td>
</tr>
<tr class="odd">
<td><p>returnOrigValue</p></td>
<td><p>Configuration node</p></td>
<td><p>Scalar</p></td>
<td><p>Returns value of a node under specified path in active config.</p></td>
</tr>
<tr class="even">
<td><p>returnValues</p></td>
<td><p>Configuration multi-value node</p></td>
<td><p>Array</p></td>
<td><p>Returns array of all values of a multi-value node under specified path in working config.</p></td>
</tr>
<tr class="odd">
<td><p>returnOrigValues</p></td>
<td><p>Configuration multi-value node</p></td>
<td><p>Array</p></td>
<td><p>Returns array of all values of a multi-value node under specified path in active config.</p></td>
</tr>
<tr class="even">
<td><p>Observers of the "effective" config</p></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr class="odd">
<td><p>isEffective</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if node under specified path is "effective".</p></td>
</tr>
<tr class="even">
<td><p>isActive</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Same to isEffective.</p></td>
</tr>
<tr class="odd">
<td><p>listEffectiveNodes</p></td>
<td><p>Configuration path</p></td>
<td><p>Aray</p></td>
<td><p>Returns array of "effective" child nodes during current commit under specified path.</p></td>
</tr>
<tr class="even">
<td><p>listOrigPlusComNodes</p></td>
<td><p>Configuration path</p></td>
<td><p>Array</p></td>
<td><p>Same to listEffectiveNodes.</p></td>
</tr>
<tr class="odd">
<td><p>returnEffectiveValue</p></td>
<td><p>Configuration node</p></td>
<td><p>Scalar</p></td>
<td><p>Returns "effective" value of a node during current commit.</p></td>
</tr>
<tr class="even">
<td><p>returnOrigPlusComValue</p></td>
<td><p>Configuration node</p></td>
<td><p>Scalar</p></td>
<td><p>Returns "effective" value of a node during current commit.</p></td>
</tr>
<tr class="odd">
<td><p>returnEffectiveValues</p></td>
<td><p>Configuraion multi-value node</p></td>
<td><p>Array</p></td>
<td><p>Returns array of "effective" values of a multi-value node during current commit.</p></td>
</tr>
<tr class="even">
<td><p>returnOrigPlusComValues</p></td>
<td><p>Configuraion multi-value node</p></td>
<td><p>Array</p></td>
<td><p>Returns array of "effective" values of a multi-value node during current commit.</p></td>
</tr>
<tr class="odd">
<td><p>isDeleted</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if node has been deleted in working config.</p></td>
</tr>
<tr class="even">
<td><p>listDeleted</p></td>
<td><p>Configuration path</p></td>
<td><p>Array</p></td>
<td><p>Returns array of nodes that have been deleted under specified level in working config.</p></td>
</tr>
<tr class="odd">
<td><p>returnDeletedValues</p></td>
<td><p>Configuration multi-value node</p></td>
<td><p>Array</p></td>
<td><p>Returns array of values of a multi-value node that have been deleted in working config.</p></td>
</tr>
<tr class="even">
<td><p>isAdded</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if specified node has been added in working config.</p></td>
</tr>
<tr class="odd">
<td><p>isChanged</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if specified node has been changed in working config.</p></td>
</tr>
<tr class="even">
<td><p>listNodeStatus</p></td>
<td><p>Configuration path</p></td>
<td><p>Hash</p></td>
<td><p>Return a hash of status of child nodes at specified level. Node name is the hash key. node status is the hash value. Node status can be one of "deleted", "added", "changed", or "static".</p></td>
</tr>
<tr class="odd">
<td><p>getTmplChildren</p></td>
<td><p>Configuration path</p></td>
<td><p>Array</p></td>
<td><p>Return list of child nodes in the template hierarchy at specified level.</p></td>
</tr>
<tr class="even">
<td><p>validateTmplPath</p></td>
<td><p>Configuration path</p></td>
<td><p>True or false</p></td>
<td><p>Return whether specified path is a valid template path.</p></td>
</tr>
<tr class="odd">
<td><p>parseTmplAll</p></td>
<td><p>Configuration path</p></td>
<td><p>Hash</p></td>
<td><p>Return hash ref of parsed template of specified path, undef if path is invalid. note: if !allow_val, path must terminate at a "node", not "value".</p></td>
</tr>
<tr class="even">
<td><p>hasTmplChildren</p></td>
<td><p>Configuration path</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if specified configuration path has child nodes.</p></td>
</tr>
<tr class="odd">
<td><p>"Deactivate-aware" observers of current working config or active config.</p></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr class="even">
<td><p>deactivated</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Return whether specified node is deactivated in working config. Note that this is different from "marked deactivated". If a node is "marked deactivated", then the node itself and any descendants are "deactivated".</p></td>
</tr>
<tr class="odd">
<td><p>deactivatedOrig</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Return whether specified node is deactivated in active config.</p></td>
</tr>
<tr class="even">
<td><p>returnValuesDA</p></td>
<td><p>Configuration multi-value node</p></td>
<td><p>Array</p></td>
<td><p>Deactivate aware version of returnValues().</p></td>
</tr>
<tr class="odd">
<td><p>returnOrigValuesDA</p></td>
<td><p>Configuration multi-value node</p></td>
<td><p>Array</p></td>
<td><p>DA version of returnOrigValues().</p></td>
</tr>
<tr class="even">
<td><p>returnValueDA</p></td>
<td><p>Configuration node</p></td>
<td><p>Scalar</p></td>
<td><p>DA version of returnOrigValue().</p></td>
</tr>
<tr class="odd">
<td><p>listOrigNodesDA</p></td>
<td><p>Configuration path</p></td>
<td><p>Array</p></td>
<td><p>DA version of listOrigNodes()</p></td>
</tr>
<tr class="even">
<td><p>listNodeStatusDA</p></td>
<td><p>Configuration path</p></td>
<td><p>Hash</p></td>
<td><p>DA version of listNodeStatus().</p></td>
</tr>
<tr class="odd">
<td><p>returnComment</p></td>
<td><p>Configuration node</p></td>
<td><p>Scalar</p></td>
<td><p>Returns comment of "node" in working config or undef if comment doesn't exist.</p></td>
</tr>
<tr class="even">
<td><p>returnOrigComment</p></td>
<td><p>Configuration node</p></td>
<td><p>Scalar</p></td>
<td><p>Returns comment of "node" in active config or undef if comment doesn't exist</p></td>
</tr>
<tr class="odd">
<td><p>High-level API functions (not using the cstore library directly)</p></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr class="even">
<td><p>setLevel</p></td>
<td><p>Configuration path</p></td>
<td><p>Current level</p></td>
<td><p>Set the current level of config hierarchy to specified level (if defined).</p></td>
</tr>
<tr class="odd">
<td><p>returnParent</p></td>
<td><p>Configuration node</p></td>
<td><p>Scalar</p></td>
<td><p>Returns the name of ancestor node relative to the current level. Each level up is represented by a ".." in the argument.</p></td>
</tr>
<tr class="even">
<td><p>parseTmpl</p></td>
<td><p>Configuration path</p></td>
<td><p>Array</p></td>
<td><p>Parse template of specified path and return ($is_multi, $is_text, $default) or undef if specified path is not valid.</p></td>
</tr>
<tr class="odd">
<td><p>isTagNode</p></td>
<td><p>Configuration path</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if specified path is a tag node.</p></td>
</tr>
<tr class="even">
<td><p>isLeafNode</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if specified path is a "leaf node", i.e., single-/multi-value node.</p></td>
</tr>
<tr class="odd">
<td><p>isLeafValue</p></td>
<td><p>Configuration node</p></td>
<td><p>True or false</p></td>
<td><p>Returns true if specified path is a "leaf value", i.e., value of a leaf node.</p></td>
</tr>
<tr class="even">
<td><p>compareValueLists</p></td>
<td><p>Original value list and new value list</p></td>
<td><p>Lists of deleted and added nodes</p></td>
<td><p>Compare two value lists and return "deleted" and "added" lists. Since this is for multi-value nodes, there is no "changed" (if a value's ordering changed, it is deleted then added).</p></td>
</tr>
</tbody>
</table>
<h2 id="usage_example">Usage example</h2>
<p>Background: Your helpdesk guys ask you to make a spreadsheet with remote-access PPTP VPN user information and keep it up to date. Of course you do not want to copy and paste this information by hand.</p>
<p>All spreadsheet software supports import from CSV, so the only thing we need to do is to extract values from config and print then as comma separated lines, passwords enclosed into double quotes for the case they contain a comma and add some header. Like this:</p>
<p><code>user,password,address,is_disabled</code><br />
<code>johnsmith,"this,isapass",192.0.2.41,no</code></p>
<p>Here we go:</p>
<pre><code>#!/usr/bin/perl```
Here we go:
#!/usr/bin/perl
use strict;
# using the Vyatta perl API
use lib ""/opt/vyatta/share/perl5/";";
use Vyatta::Config;
# Settings
my $proto = ""pptp";";
my $delimiter = ",";",";
# CSV RFC4180 requires to use CRLF (\r\n) as line break
my $header = ""user,password,address,disabled\r\n";";
# Create a config instance
my $config = new Vyatta::Config;
# Set default config level, this allows to use relative paths
$config->>setLevel("vpn"vpn pptp remote-access authentication local-users username");");
# Obtain array of user names
my @users = $config->>listNodes();
# Print file header
print $header;
# Now walk through the user names, obtain values and print them
foreach my $user (@users) {
# Since we set config level to "vpn"vpn pptp remote-access authentication local-users username""
# we now can specify only the remaining part as methods argument,
# it will be appended to the path we used in setLevel()
my $password = $config->>returnValue(""$user password");");
my $address = $config->>returnValue(""$user static-ip");");
#" #"disable"" is a leaf node with no value, so we should check
# if it exists instead of obtaining its value
my $disabled = $config->>exists(""$user disable") ? "yes"") ? : "no";"yes" : "no";
# It's # It's not prohibited to use ",""," in passwords,
# so we should enclose them into quotes to prevent
# the parser from treating them as delimiters
$password = "\""\"$password\"";"";
my $line = join($delimiter, $user, $password, $address, $disabled);
print ""$line\r\n";";
}</code></pre>
<p> }
Check it works:</p>
<pre><code>
vyatta@R1# show vpn pptp remote-access authentication local-users
username joerandomuser {
disable
password qwerrty
static-ip 10.91.17.105
}
username johnsmith {
password this,isapass
}
vyatta@R1# perl ./pptpusers.pl
user,password,address,disabled
joerandomuser,""qwerrty"",10.91.17.105,yes
johnsmith,"this,isapass",,no</code></pre>
<p><a href="Category:_Development" title="wikilink">Category: Development</a></p> johnsmith,"this,isapass",,no