Perl Configd Client Library

Introduction

Please refer to Configd Client Library for the general concepts behind the API. This document will cover only Perl specifics.

Mechanics

Before we can use the configd API we need to establish a connection to the daemon this is done when a Client object is instantiated. Each client object represents a new connection to configd so they should be shared to avoid connection setup overhead. When the Client object is collected, the connection is terminated.

1 2 3 4 5 6 7 8 9 #!/usr/bin/perl use strict; use warnings; use lib "/opt/vyatta/share/perl5"; use Vyatta::Configd; my $client = Vyatta::Configd::Client->new();

Once connected we can do a variety of actions on the system, one can configure the device, request the operational state of the device, or perform feature specific RPCs. When configuring the device via the Configd APIs one follows much the same procedure as with the CLI. One creates a configuration session, makes changes, commits those changes, then tears down the session. One may view the RUNNING datastore without a session being created. Sessions persist process exit and must be explicitly removed with "session_teardown". The minimal configuration application looks like the following.

1 2 3 4 5 6 7 8 9 10 11 12 #!/usr/bin/perl use strict; use warnings; use lib "/opt/vyatta/share/perl5"; use Vyatta::Configd; my $client = Vyatta::Configd::Client->new(); $client->session_setup("$$"); # do something with the config $client->session_teardown();

From here, one may perform actions similar to what one does on the CLI. Since the interface here is meant for programatic interaction, one may also introspect on the data-model and the current state of the candidate tree to determine available actions, this is similar to using "tab-completion" to inspect the CLI.

Examples

Configuration

The following example uses the Perl configd API to set all dataplane interfaces to listen for DHCP addresses if no other address is assigned to that interface. While this is a silly thing to do, it demonstrates the basic mechanics of the this API.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 #!/usr/bin/perl use strict; use warnings; use Try::Tiny; use lib "/opt/vyatta/share/perl5"; use Vyatta::Configd; sub setup_interface_address { my ($client, $intf) = @_; printf "%s:", $intf; my $path = "interfaces dataplane $intf address"; my @addrs = $client->get($path); printf("%s\n", join(", ", @addrs)); $client->set($path." dhcp") if (scalar(@addrs) == 0); } my $client = Vyatta::Configd::Client->new(); $client->session_setup("$$"); try { map { setup_interface_address($client, $_) } $client->get("interfaces dataplane"); $client->commit("setup interface addresses"); } catch { warn "$_"; }; $client->session_teardown();

Below is a sample run of the above application.

1 2 3 4 $ perl configdapi.pl dp0s3:10.156.58.201/23 dp0s10: dp0s11:

RPC

One can also call an RPC via this interface. The Perl API has a special helper to enable native hash tables to be used for RPC input and output. The Perl API also exposes the string based raw call_rpc method if required.

1 2 3 4 5 6 7 8 9 10 #!/usr/bin/perl use strict; use warnings; use lib "/opt/vyatta/share/perl5"; use Vyatta::Configd; my $client = Vyatta::Configd::Client->new(); my $output = $client->call_rpc_hash("vyatta-op-v1", "ping", {"host"=>"1.1.1.1"}); printf "rx-packet-count %s\n", $output->{"rx-packet-count"};

Below is an example run of the RPC application.

1 2 $ perl configdapi.pl rx-packet-count 3

Operational State Data

Finally one may query for operational data information. The Perl API has a special helper to enable the return of native hash tables representing the state tree. The Perl API also exposes the string based  raw tree_get_full method if required.

1 2 3 4 5 6 7 8 9 10 #!/usr/bin/perl use strict; use warnings; use lib "/opt/vyatta/share/perl5"; use Vyatta::Configd; my $client = Vyatta::Configd::Client->new(); my $tree = $client->tree_get_full_hash("system state platform", {"encoding"=>"rfc7951"}); printf "OS Release: %s\n", $tree->{"vyatta-system-v1:platform"}->{"os-release"};

Below is an example execution of this program.

1 2 $ perl configdapi.pl OS Release: Vyatta:Master

Method documentation

The Perl API is generated using SWIG from the C++ API. CamelCase method names are converted to under_case method names and the appropriate input and output conversions to Perl native data types are done. See the C++ documentation for the list of available methods and documentation.

Paths

Paths provided via the Perl API may either Arrays or space separated strings and will be converted to the appropriate C++ type automatically before calling the underlying method.

Special Methods

As mentioned in the examples section the Perl API provides several special methods to work better natively. Below are the provided methods.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 sub get { my ($self, $path, $database) = @_; $database = $AUTO unless defined $database; $self->node_get($database, $path); } sub tree_get_hash { my ($self, $path, $opts) = @_; $opts->{'encoding'} = "json" unless defined $opts->{'encoding'}; $opts->{'database'} = $AUTO unless defined $opts->{'database'}; my $res = $self->tree_get_encoding($opts->{'database'}, $path, $opts->{'encoding'}); return unless defined $res; return from_json($res); } sub tree_get_full_hash { my ($self, $path, $opts) = @_; $opts->{'encoding'} = "json" unless defined $opts->{'encoding'}; $opts->{'database'} = $AUTO unless defined $opts->{'database'}; my $res = $self->tree_get_full_encoding($opts->{'database'}, $path, $opts->{'encoding'}); return unless defined $res; return from_json($res); } sub call_rpc_hash { my ($self, $ns, $name, $input) = @_; my $inputStr = to_json($input); return unless defined $inputStr; my $output = $self->call_rpc($ns, $name, $inputStr); return unless defined $output; return from_json($output); }