Page MenuHomeVyOS Platform

Perl API
Updated 1,439 Days AgoPublic

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:
MethodArgumentsReturnsPurpose
existsConfiguration nodeTrue or falseReturns true if specified node exists in current working config.
existsOrigConfiguration nodeTrue or falseReturns true if specified node exists in current active (running) config.
isDefaultConfiguration nodeTrue or falseReturns true if specified node has default value in current working config.
isDefaultOrigConfiguration nodeTrue or falseReturns true if specified node had default value in current active (running) config.
listNodesConfiguration pathArrayReturns array of all child nodes under specified path in working config.
listOrigNodesConfiguration pathArrayReturns array of all child nodes under specified path in active config.
returnValueConfiguration nodeScalarReturns value of a node under specified path in working config.
returnOrigValueConfiguration nodeScalarReturns value of a node under specified path in active config.
returnValuesConfiguration multi-value nodeArrayReturns array of all values of a multi-value node under specified path in working config.
returnOrigValuesConfiguration multi-value nodeArrayReturns array of all values of a multi-value node under specified path in active config.
  • Observers of the "effective" config:
isEffectiveConfiguration nodeTrue or falseReturns true if node under specified path is "effective".
isActiveConfiguration nodeTrue or falseSame to isEffective.
listEffectiveNodesConfiguration pathArayReturns array of "effective" child nodes during current commit under specified path.
listOrigPlusComNodesConfiguration pathArraySame to listEffectiveNodes.
returnEffectiveValueConfiguration nodeScalarReturns "effective" value of a node during current commit.
returnOrigPlusComValueConfiguration nodeScalarReturns "effective" value of a node during current commit.
returnEffectiveValuesConfiguraion multi-value nodeArrayReturns array of "effective" values of a multi-value node during current commit.
returnOrigPlusComValuesConfiguraion multi-value nodeArrayReturns array of "effective" values of a multi-value node during current commit.
isDeletedConfiguration nodeTrue or falseReturns true if node has been deleted in working config.
listDeletedConfiguration pathArrayReturns array of nodes that have been deleted under specified level in working config.
returnDeletedValuesConfiguration multi-value nodeArrayReturns array of values of a multi-value node that have been deleted in working config.
isAddedConfiguration nodeTrue or falseReturns true if specified node has been added in working config.
isChangedConfiguration nodeTrue or falseReturns true if specified node has been changed in working config.
listNodeStatusConfiguration pathHashReturn 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".
getTmplChildrenConfiguration pathArrayReturn list of child nodes in the template hierarchy at specified level.
validateTmplPathConfiguration pathTrue or falseReturn whether specified path is a valid template path.
parseTmplAllConfiguration pathHashReturn 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".
hasTmplChildrenConfiguration pathTrue or falseReturns 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.

deactivatedConfiguration nodeTrue or falseReturn 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".
deactivatedOrigConfiguration nodeTrue or falseReturn whether specified node is deactivated in active config.
returnValuesDAConfiguration multi-value nodeArrayDeactivate aware version of returnValues().
returnOrigValuesDAConfiguration multi-value nodeArrayDA version of returnOrigValues().
returnValueDAConfiguration nodeScalarDA version of returnOrigValue().
listOrigNodesDAConfiguration pathArrayDA version of listOrigNodes()
listNodeStatusDAConfiguration pathHashDA version of listNodeStatus().
returnCommentConfiguration nodeScalarReturns comment of "node" in working config or undef if comment doesn't exist.
returnOrigCommentConfiguration nodeScalarReturns comment of "node" in active config or undef if comment doesn't exist
  • High-level API functions (not using the cstore library directly):
setLevelConfiguration pathCurrent levelSet the current level of config hierarchy to specified level (if defined).
returnParentConfiguration nodeScalarReturns the name of ancestor node relative to the current level. Each level up is represented by a ".." in the argument.
parseTmplConfiguration pathArrayParse template of specified path and return ($is_multi, $is_text, $default) or undef if specified path is not valid.
isTagNodeConfiguration pathTrue or falseReturns true if specified path is a tag node.
isLeafNodeConfiguration nodeTrue or falseReturns true if specified path is a "leaf node", i.e., single-/multi-value node.
isLeafValueConfiguration nodeTrue or falseReturns true if specified path is a "leaf value", i.e., value of a leaf node.
compareValueListsOriginal value list and new value listLists of deleted and added nodesCompare 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
Last Author
Unknown Object (User)
Last Edited
Apr 19 2020, 11:21 PM

Event Timeline

Unknown Object (User) deleted this document.Apr 14 2020, 10:03 PM
Unknown Object (User) created this object.
Unknown Object (User) edited the content of this document. (Show Details)Apr 15 2020, 7:59 PM
Unknown Object (User) edited the content of this document. (Show Details)Apr 15 2020, 8:03 PM
Unknown Object (User) edited the content of this document. (Show Details)Apr 16 2020, 11:47 AM
Unknown Object (User) edited the content of this document. (Show Details)Apr 19 2020, 11:21 PM
Unknown Object (User) published a new version of this document.