/
C++ Configd Client Library

C++ Configd Client Library

Owned by John Southworth
Nov 10, 2020

Introduction

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

Mechanics

Before we can use the configd API we need to establish a connection to the daemon, instantiating the CfgClient object will do this. The destructor for the client object will close the connection.

#include <vyatta-cfg/client/CfgClient.hpp> int main() { CfgClient client; }

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 SessionTeardown. The minimal configuration application looks like the following.

#include <string> #include <sstream> #include <unistd.h> #include <sys/types.h> #include <vyatta-cfg/client/CfgClient.hpp> int main() { CfgClient client; stringstream ss; ss << getpid(); client.SessionSetup(ss.str()); // do something to the configuration client.SessionTeardown(); }

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 C++ 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.

#include <string> #include <vector> #include <iterator> #include <iostream> #include <unistd.h> #include <sys/types.h> #include <vyatta-cfg/client/CfgClient.hpp> using namespace std; void setup_interface_address(CfgClient& client, string intf_name) { cout << intf_name << ":"; vector<string> path { "interfaces", "dataplane", intf_name, "address" }; auto addrs = client.NodeGet(CfgClient::AUTO, path); copy(addrs.begin(), addrs.end(), ostream_iterator<string>(cout, ", ")); cout << endl; if (addrs.size() == 0) { path.push_back("dhcp"); client.Set(path); } } int main() { CfgClient client; stringstream ss; ss << getpid(); client.SessionSetup(ss.str()); try { for (auto interface : client.NodeGet(CfgClient::AUTO, { "interfaces", "dataplane" })) { setup_interface_address(client, interface); } client.Commit("setup interface addresses"); } catch (CfgClientException e) { cerr << e.what(); } client.SessionTeardown(); return 0; }

Below is a sample run of the above application.

$ g++ -std=c++11 -lvyatta-config -o configdapi configdapi.cpp $ ./configdapi dp0s3:10.156.58.201/23, dp0s10: dp0s11:

RPC

One can also call an RPC via this interface.

#include <string> #include <iostream> #include <json/json.h> #include <vyatta-cfg/client/CfgClient.hpp> using namespace std; int main() { CfgClient client; Json::Value input; Json::Value output; Json::Reader reader; input["host"] = "1.1.1.1"; auto outputs = client.CallRPC("vyatta-op-v1", "ping", input.toStyledString()); reader.parse(outputs, output); cout << "rx-packet-count " << output["rx-packet-count"] << endl; }

Below is an example run of the RPC application.

$ g++ -std=c++11 -lvyatta-config $(pkg-config --cflags --libs jsoncpp) -o configdapi configdapi.cpp $ ./configdapi rx-packet-count 3

Operational State Data

Finally one may query for operational data information.

#include <string> #include <iostream> #include <json/json.h> #include <vyatta-cfg/client/CfgClient.hpp> using namespace std; int main() { CfgClient client; Json::Value tree; Json::Reader reader; auto trees = client.TreeGetFullEncoding( CfgClient::AUTO, {"system", "state", "platform"}, "rfc7951" ); reader.parse(trees, tree); cout << "OS Release:" << tree["vyatta-system-v1:platform"]["os-release"] << endl; }

Below is an example execution of this program.

$ g++ -std=c++11 -lvyatta-config $(pkg-config --cflags --libs jsoncpp) -o configdapi configdapi.cpp $ ./configdapi OS Release:"Vyatta:Master"



Man Page

The following documentation was generated automatically using Doxygen.

CfgClient

CfgClient(3) Vyatta Configuration System CfgClient(3) NAME CfgClient SYNOPSIS #include <CfgClient.hpp> Public Types enum Database { AUTO, RUNNING, CANDIDATE, EFFECTIVE } enum NodeStatus { UNCHANGED, CHANGED, ADDED, DELETED } enum NodeType { LEAF, MULTI, CONTAINER, TAG } Public Member Functions CfgClient () throw (CfgClientFatalException) ~CfgClient () void SessionAttach (const std::string &sessid) throw (CfgClientException) void SessionSetup (const std::string &sessid) throw (CfgClientException) void SessionTeardown () throw (CfgClientException) bool SessionChanged () throw (CfgClientException) bool SessionSaved () throw (CfgClientException) void SessionMarkSaved () throw (CfgClientException) void SessionMarkUnsaved () throw (CfgClientException) bool SessionLocked () throw (CfgClientException) void SessionLock () throw (CfgClientException) void SessionUnlock () throw (CfgClientException) bool SessionExists () throw (CfgClientException) std::string Set (const std::vector< std::string > &path) throw (CfgClientException) std::string Delete (const std::vector< std::string > &path) throw (CfgClientException) std::string ValidatePath (const std::vector< std::string > &path) throw (CfgClientException) std::string Commit (const std::string &comment) throw (CfgClientException) std::string Discard () throw (CfgClientException) std::string Validate () throw (CfgClientException) std::string Save () throw (CfgClientException) bool Load (const std::string &file) throw (CfgClientException) bool Merge (const std::string &file) throw (CfgClientException) std::map< std::string, std::string > TemplateGet (const std::vector< std::string > &path) throw (CfgClientException) std::vector< std::string > TemplateGetChildren (const std::vector< std::string > &path) throw (CfgClientException) std::vector< std::string > TemplateGetAllowed (const std::vector< std::string > &path) throw (CfgClientException) bool TemplateValidatePath (const std::vector< std::string > &path) throw (CfgClientException) bool TemplateValidateValues (const std::vector< std::string > &path) throw (CfgClientException) std::map< std::string, std::vector< std::string > > GetFeatures (void) throw (CfgClientException) std::map< std::string, std::string > GetHelp (const std::vector< std::string > &path, bool FromSchema) throw (CfgClientException) bool NodeExists (Database db, const std::vector< std::string > &path) throw (CfgClientException) bool NodeIsDefault (Database db, const std::vector< std::string > &path) throw (CfgClientException) std::vector< std::string > NodeGet (Database db, const std::vector< std::string > &path) throw (CfgClientException) NodeStatus NodeGetStatus (Database db, const std::vector< std::string > &path) throw (CfgClientException) NodeType NodeGetType (const std::vector< std::string > &path) throw (CfgClientException) std::string TreeGetEncoding (Database db, const std::vector< std::string > &path, const std::string &encoding) throw (CfgClientException) std::string TreeGetFullEncoding (Database db, const std::vector< std::string > &path, const std::string &encoding) throw (CfgClientException) std::string TreeGet (Database db, const std::vector< std::string > &path) throw (CfgClientException) std::string TreeGetXML (Database db, const std::vector< std::string > &path) throw (CfgClientException) std::string TreeGetInternal (Database db, const std::vector< std::string > &path) throw (CfgClientException) std::string TreeGetFull (Database db, const std::vector< std::string > &path) throw (CfgClientException) std::string TreeGetFullXML (Database db, const std::vector< std::string > &path) throw (CfgClientException) std::string TreeGetFullInternal (Database db, const std::vector< std::string > &path) throw (CfgClientException) std::string CallRPC (const std::string ns, const std::string name, const std::string input) throw (CfgClientException) std::string CallRPCXML (const std::string ns, const std::string name, const std::string input) throw (CfgClientException) std::string EditConfigXML (const std::string target, const std::string default_operation, const std::string test_option, const std::string error_option, const std::string config) throw (CfgClientException) Member Enumeration Documentation enum CfgClient::Database Database defines what database to use for the query. Enumerator AUTO AUTO will select CANDIDATE when the client is attached to a session, RUNNING otherwise. RUNNING RUNNING is the current running configuration. CANDIDATE CANDIDATE is the current session's temporary database. RUNNING if there is no session. In other words this tries to do the right thing. EFFECTIVE EFFECTIVE is DEPRECATED, do not use unless you know why you are using it. Deprecated This is treated as CANDIDATE but left for compatibility with older uses. enum CfgClient::NodeStatus NodeStatus() represents the current change status of the node. When querying the RUNNING tree this will always be UNCHANGED. When querying the CANDIDATE tree this will be the change state when compared to the RUNNING tree. Enumerator UNCHANGED UNCHANGED the values are the same in RUNNING and CANDIDATE CHANGED CHANGED the values are different in RUNNING and CANDIDATE ADDED ADDED the value is new in the CANDIDATE tree DELETED DELETED the value has been removed from the CANDIDATE tree. enum CfgClient::NodeType NodeType is DEPRECATED Deprecated The documenation here is for understanding old users of this method. NodeType represents the older Vyatta specific names for node types. These map roughly to the YANG types as follows. Lists in the Vyatta system are represented by the key being part of the path. These 'list entries' are also represented as containers. Note: There is not currently a direct replacement for this API instead we encourage the use of the TreeGet with JSON_ENCODING so that the structure of the data returned reflects the schema information. Enumerator LEAF YANG leaf MULTI YANG leaf-list CONTAINER YANG container TAG YANG list Constructor & Destructor Documentation CfgClient::CfgClient ()CfgClientFatalException CfgClient() creates a new connection to configd. This will create a connection to configd and will inherit a configuration session from the environment if one exists. The CfgClientFatalException will be thrown if a connection cannot be established. CfgClient::~CfgClient () ~CfgClient() disconnects from configd. This doesn't teardown configuration sessions automatically since this object may be used in a non-configuration or in a shared configuration context. Use SessionTeardown() to destroy sessions. Member Function Documentation void CfgClient::SessionAttach (const std::string & sessid)CfgClientException SessionAttach() attaches to the provided session id. If the session does not exist then an exception is raised. void CfgClient::SessionSetup (const std::string & sessid)CfgClientException SessionSetup() creates a new configuration session and makes that session the context for this instance object. Commonly the pid of the process is used as the session id, but this may be any arbitrary string. void CfgClient::SessionTeardown ()CfgClientException SessionTeardown() destroys a configuration session. Care should be taken that you really want to teardown the session, in some contexts it may not be appropriate for this client to destroy a session. All sessions should be destroyed as soon as they are no longer needed as configd maintains the state indefinitiely unless told to destroy it. bool CfgClient::SessionChanged ()CfgClientException SessionChanged() reports whether the current session has any configuration changes. bool CfgClient::SessionSaved ()CfgClientException SessionSaved() reports whether the current configuration session has been saved to the running configuration. void CfgClient::SessionMarkSaved ()CfgClientException SessionMarkSaved() allows one to effect the saved state of the session. Deprecated SessionMarkSaved is DEPRECATED. void CfgClient::SessionMarkUnsaved ()CfgClientException SessionMarkUnsaved() allows one to effect the saved state of the session. Deprecated SessionMarkUnsaved is DEPRECATED. bool CfgClient::SessionLocked ()CfgClientException SessionLocked() reports whether or not the current session is locked. Locks can be taken to prevent multiple writers to a shared session. Locks also prevent changes during commit. A session's lock is released if the client that took the lock disconnects. void CfgClient::SessionLock ()CfgClientException SessionLock() will attempt to lock the current session. If the session is currently locked then the exception will be raised. void CfgClient::SessionUnlock ()CfgClientException SessionUnlock() will attempt to unlock the current session. If the session is currently not locked by this process, then the exception will be raised. bool CfgClient::SessionExists ()CfgClientException SessionExists() reports whether the current session still exists. This allows for testing if a shared session has been torn down by another instance. std::string CfgClient::Set (const std::vector< std::string > & path)CfgClientException Set() creates a new path in the configuration datastore. The client needs to be attached to a configuration session for this call to work. If any error occurs that error is thrown as an exception. Creating a path that already exists is considered an error. Parameters path The path to the configuration represented as a vector Returns Any informational messages that occurred during set std::string CfgClient::Delete (const std::vector< std::string > & path)CfgClientException Delete() removes a path in the configuration datastore. The client needs to be attached to a configuration session for this call to work. If any error occurs that error is thrown as an exception. Deleting a path that does not exist is considered an error. Parameters path The path to the configuration represented as a vector Returns Any informational messages that occurred during delete std::string CfgClient::ValidatePath (const std::vector< std::string > & path)CfgClientException ValidatePath() checks that the path can be set Parameters path The path to the configuration represented as a vector Returns Any informational messages that occurred during the validation Invalid paths will throw an exception. std::string CfgClient::Commit (const std::string & comment)CfgClientException Commit() validates and applies the candidate configuration. The candidate configuration is applied to the running system resulting in the running configuration being updated if the transaction is successful. Parameters comment A comment that describes the changes during this commit. An empty string is allowed for no description. Returns Any informational messages reported during the commit. std::string CfgClient::Discard ()CfgClientException Discard() throws away all pending (uncommitted) changes for this session. std::string CfgClient::Validate ()CfgClientException Validate() checks that the candidate configuration meets all the constraints modeled in the schema. std::string CfgClient::Save ()CfgClientException Save() Saves the current running configuration to the 'saved' configuration. bool CfgClient::Load (const std::string & file)CfgClientException Load() Replaces the configuration with the config in the supplied file in the candidate database. bool CfgClient::Merge (const std::string & file)CfgClientException Merge() Merges the configuration with the config in the supplied file in the candidate database. std::map<std::string, std::string> CfgClient::TemplateGet (const std::vector< std::string > & path)CfgClientException TemplateGet() is DEPRECATED. Deprecated The documenation here is for understanding old users of this method. This returns a map consisting of a template of the configuration data that is compatible with older internal Vyatta software. The names of the fields of this map are using old terminology and the types represented are not valid according to the YANG spec. Parameters path The path to the configuration represented as a vector Returns A map representing the values in the template. No more documentation will be provided for this, if you don't know what these values mean you shouldn't be using them. std::vector<std::string> CfgClient::TemplateGetChildren (const std::vector< std::string > & path)CfgClientException TemplateGetChildren() access the children of the schema node at a given path Template is an old name kept for historical reasons; this accesses the YANG schema tree. Parameters path The path in the schema tree. Returns The children at the requested path. std::vector<std::string> CfgClient::TemplateGetAllowed (const std::vector< std::string > & path)CfgClientException TemplateGetAllowed() runs the configd:allowed extension to get the help values for a value node in the schema tree. Template is an old name kept for historical reasons; this accesses the YANG schema tree. Parameters path The path in the schema tree. Returns The allowed values for the requested path. bool CfgClient::TemplateValidatePath (const std::vector< std::string > & path)CfgClientException TemplateValidatePath() determine if the path is valid according to the schema. Template is an old name kept for historical reasons; this accesses the YANG schema tree. Parameters path The path in the schema tree. Returns Whether the path is valid according to the schema. bool CfgClient::TemplateValidateValues (const std::vector< std::string > & path)CfgClientException TemplateValidatePathValues() determines if the path is valid according to the schema and validates all values according to the schema syntax. For historical reasons this is not the same as TemplateValidatePath, which does not evaluate syntax. Chances are this is the method one wants to use. Template is an old name kept for historical reasons; this accesses the YANG schema tree. Parameters path The path in the schema tree. Returns Whether the path is valid according to the schema. std::map<std::string, std::vector<std::string> > CfgClient::GetFeatures (void)CfgClientException GetFeatures() Get map of schema ids and the corresponding enabled features. Returns A map of schema features. std::map<std::string, std::string> CfgClient::GetHelp (const std::vector< std::string > & path, bool FromSchema)CfgClientException GetHelp() returns a map containing the children and their help strings Parameters path The path of the parent for which one wants help as a vector FromSchema informs configd to generate help from the schema definition as well as from the data tree. If false help is from data existing in the tree only. bool CfgClient::NodeExists (Database db, const std::vector< std::string > & path)CfgClientException NodeExists() reports whether the path exists in the requested database. Parameters db The database one wishes to query. path The path to the configuration represented as a vector. Returns Whether the path exists in the requested database bool CfgClient::NodeIsDefault (Database db, const std::vector< std::string > & path)CfgClientException NodeIsDefault() reports whether the path is a default in the requested database. Parameters db The database one wishes to query. path The path to the configuration represented as a vector. Returns Whether the path is a default in the requested database std::vector<std::string> CfgClient::NodeGet (Database db, const std::vector< std::string > & path)CfgClientException NodeGet() queries the database for the values at a given path. Parameters db The database one wishes to query. path The path to the configuration represented as a vector. Returns The children values of the given path. NodeStatus CfgClient::NodeGetStatus (Database db, const std::vector< std::string > & path)CfgClientException NodeGetStatus() reports the status of a node in the tree. Parameters db The database one wishes to query. path The path to the configuration represented as a vector. Returns The status of the node see NodeStatus for descriptions. NodeType CfgClient::NodeGetType (const std::vector< std::string > & path)CfgClientException NodeGetType() is DEPRECATED Deprecated The documenation here is for understanding old users of this method. Parameters path The path to the configuration represented as a vector. Returns NodeType represents the older Vyatta specific names for node types. See NodeType for information. std::string CfgClient::TreeGetEncoding (Database db, const std::vector< std::string > & path, const std::string & encoding)CfgClientException The below APIs support the following strings as encodings: Parameters db The database to get the tree From. path The configuration path at which to root the sub-tree. encoding The desired encoding. Returns A string in the desired encoding representing the tree at the given location. std::string CfgClient::TreeGetFullEncoding (Database db, const std::vector< std::string > & path, const std::string & encoding)CfgClientException TreeGetFullEncoding() provides access to sub-trees of the operational datastore. The operational datastore consists of the configuration database and any modeled operational state data. These trees are encoded in the desired encoding and returned as a string. Parameters db The database to get the tree From. path The configuration path at which to root the sub-tree. encoding The desired encoding. Returns A string in the desired encoding representing the tree at the given location. std::string CfgClient::TreeGet (Database db, const std::vector< std::string > & path)CfgClientException TreeGet() provides access to sub-trees of the configuration database. This call is equivalent to TreeGetEncoding with JSON_ENCODING. Parameters db The database to get the tree From. path The configuration path at which to root the sub-tree. Returns A string in the desired encoding representing the tree at the given location. std::string CfgClient::TreeGetXML (Database db, const std::vector< std::string > & path)CfgClientException TreeGetXML() provides access to sub-trees of the configuration database. This call is equivalent to TreeGetEncoding with XML_ENCODING. Parameters db The database to get the tree From. path The configuration path at which to root the sub-tree. Returns A string in the desired encoding representing the tree at the given location. std::string CfgClient::TreeGetInternal (Database db, const std::vector< std::string > & path)CfgClientException TreeGetInternal() provides access to sub-trees of the configuration database. This call is equivalent to TreeGetEncoding with INTERNAL_ENCODING. Parameters db The database to get the tree From. path The configuration path at which to root the sub-tree. Returns A string in the desired encoding representing the tree at the given location. std::string CfgClient::TreeGetFull (Database db, const std::vector< std::string > & path)CfgClientException TreeGetFull() provides access to sub-trees of the operational datastore. The operational datastore consists of the configuration database and any modeled operational state data. This call is equivalent to TreeGetFullEncoding with JSON_ENCODING. Parameters db The database to get the tree From. path The configuration path at which to root the sub-tree. Returns A string in the desired encoding representing the tree at the given location. std::string CfgClient::TreeGetFullXML (Database db, const std::vector< std::string > & path)CfgClientException TreeGetFullXML() provides access to sub-trees of the operational datastore. The operational datastore consists of the configuration database and any modeled operational state data. This call is equivalent to TreeGetFullEncoding with XML_ENCODING. Parameters db The database to get the tree From. path The configuration path at which to root the sub-tree. Returns A string in the desired encoding representing the tree at the given location. std::string CfgClient::TreeGetFullInternal (Database db, const std::vector< std::string > & path)CfgClientException TreeGetFullInternal() provides access to sub-trees of the operational datastore. The operational datastore consists of the configuration database and any modeled operational state data. This call is equivalent to TreeGetFullEncoding with INTERNAL_ENCODING. Parameters db The database to get the tree From. path The configuration path at which to root the sub-tree. Returns A string in the desired encoding representing the tree at the given location. std::string CfgClient::CallRPC (const std::string ns, const std::string name, const std::string input)CfgClientException CallRPC() Will call RPCs defined in yang data-models. Parameters ns The XML namespace for the model in which the RPC is defined. name The name of the RPC to call input The input definition of the schema defined in JSON_ENCODING. Returns The output schema defined in the RPC in JSON_ENCODING. std::string CfgClient::CallRPCXML (const std::string ns, const std::string name, const std::string input)CfgClientException CallRPCXML() Will call RPCs defined in yang data-models. Parameters ns The XML namespace for the model in which the RPC is defined. name The name of the RPC to call input The input definition of the schema defined in XML_ENCODING. Returns The output schema defined in the RPC in XML_ENCODING. std::string CfgClient::EditConfigXML (const std::string target, const std::string default_operation, const std::string test_option, const std::string error_option, const std::string config)CfgClientException EditConfigXML will perform a RFC-6241 edit-config operation, see RFC-6241 for more information. Parameters target The target datastore, can be 'candidate', 'running'. default_operation The operation to perform on any node that doesn't specify the operation, may be 'merge', 'replace', or 'none'. test_option The testing option, may be 'test-then-set', 'set', or 'test-only'. error_option The operation to perform when an error is encountered, may be 'stop-on-error', 'continue-on-error', or 'rollback-on- error'. config The XML data for an edit-config operation rooted at '<config>'. Author Generated automatically by Doxygen for Vyatta Configuration System from the source code. Version Version 0.104 Tue Jun 2 2020 CfgClient(3)