The configd API allows scripts to manage the Vyatta system through configd, the YANG based data model management daemon. The configd API is available in a variety of languages Go, C, C++, Perl, Python, and Ruby. The Go library is independent of the others and used to implement many of the internal tools used in the Vyatta system. The C API is the lowest layer of the other APIs. The C++ API exists to provide an object-oriented interface to the C API. The Perl, Python, and Ruby APIs are generated using SWIG from the C++ API. Each of the wrapped APIs are tweaked (using SWIG's customization mechanisms) to follow the conventions of the target language.

The actual structure of the data is defined in the YANG models and varies freely from the configd API. The following categories of actions can be performed by this API.

1 Configuration
- 1.1 Setting up a configuration session
- 1.2 Changing configuration
- 1.3 A note on databases
- 1.4 A note on encoding
2 Operational State Retrieval
3 RPCs
- 3.1 The 'vyatta-opd:command' RPC and un-modeled operational state

Configuration

Configuring the device via the configd API is very similar to configuring the device using the CLI. This is no accident, the CLI uses this API internally to interact with configd. It is not recommended that configd be treated as a source of truth for a given application's configuration information. This information should be written out so the feature may access it without involving configd. This API is most useful when writing management plane protocols or scripts. If one is retrieving multiple pieces of information via this API using the tree_get mechanisms is recommended so if one does a commit while retrieving the information one will see a consistent snapshot of the data.

Setting up a configuration session

If the client is initialized inside of a configuration session it will inherit the session id from the environment. If this is not what is desired, a new session may be created at anytime using the 'session_setup' API. From the operational mode context, 'session_setup' is required before configuration commands will work.

The session setup API is defined as possible.

client.session_setup(str(os.getpid()))

Session identifiers must be a unique string. A common practice is to use the process id. Sessions persist between process invocations so one must manually tear down the session using "session_teardown" when one is finished configuring the device.

Changing configuration

After ensuring the process has a configuration session, one can manipulate configuration data. A slight word of warning, these methods all return a string that contains any informational data returned by the system, if there is an error a 'configd.Exception' is thrown. Most return values can safely be ignored if the informational message is not desired.

The most common manipulation methods are the following (in pseudo code):

path: Space separated string or Sequence of strings representing the configuration path
 
get(path) -> list of string
tree_get(path) -> map
node_exists(Database, path) -> bool
 
validate_path(path) -> string
set(path) -> string
delete(path) -> string
 
discard() -> string
validate() -> string
commit(string) -> string

configd.Exceptions get thrown when an error occurs, this includes providing invalid paths to methods.

>>> client.set("foo bar")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/lib/python2.7/dist-packages/vyatta/configd.py", line 298, in set
    return _configd.Client_set(self, *args)
vyatta.configd.Exception: Configuration path: foo bar [foo] is not valid

A note on databases

When working with configuration, a database is a required parameter. There are 3 options for database parameters on the configd API calls

Database	Description

Database	Description
AUTO	Select appropriate database depending on the context. Operational mode, RUNNING. Configuration Mode, CANDIDATE
RUNNING	The committed configuration
CANDIDATE	The configuration information for the current configuration session. This will fall back to RUNNING if called from outside of a session.

A note on encoding

There are 3 available JSON encodings each encodes lists in a different way as described below.

Encoding	Description

Encoding	Description
"json"	Loosely based on the encoding defined by the RESTCONF spec. It encodes lists as a list of objects with the entries keys represented as elements of the objects. The difference between this and "rfc7951" is the omission of module names in the object keys. This should be considered deprecated for most purposes and "rfc7951" used instead.
"internal"	Vyatta specific encoding. It encodes lists as a dictionary with the entries keys represented as the keys to the dictionary. This should be considered deprecated for most purposes and "rfc7951" used instead.
"rfc7951"	The real RFC7951 JSON encoding.

Operational State Retrieval

Operational data in the YANG data-modeling language is encoded as nodes in a read-only data tree. The data encoded in this tree varies freely from the configuration. It represents the runtime state of the system. The operational tree and configuration tree are returned together if both types of nodes exist within the modeled hierarchy.

This tree can be requested from configd using the 'tree_get_full' family of method calls. Each of these allow the programmer to select what encoding they wish to receive. Perl, Python and Ruby have helper methods to return this data as a native data-structure. These are documented in greater detail in the individual page for each implementation.

RPCs

RPCs are calls that may be made to individual services. They are defined by the YANG definitions for the service and will vary independently of this API. The YANG specification defines an object as input and an object as output. Perl, Python and Ruby have helper methods to return this data as a native data-structure. These are documented in greater detail in the individual page for each implementation.

The 'vyatta-opd:command' RPC and un-modeled operational state

Some operational state in the Vyatta system has yet to be properly modeled by YANG, as a convenience there is an RPC call for the operational mode daemon that will return the output of any 'show' command on the system, until more operational state is available.

The RPC is defined as:

       rpc command {
                configd:call-rpc "oprpc";
                input {
                        leaf command {
                                type enumeration {
                                        enum show;
                                }
                                default show;
                        }
                        leaf args {
                                type string;
                        }
                }
                output {
                        leaf output {
                                type string;
                        }
                }
        }

DANOS

Configd Client Library