---

Module econfd_cdb

• Description
• Data Types
• Function Index
• Function Details

An Erlang interface equivalent to the CDB C-API (documented in confd_lib_cdb(3)).

Version: 5.7.19

Description

An Erlang interface equivalent to the CDB C-API (documented in confd_lib_cdb(3)).

The econfd_cdb library is used to connect to the ConfD built in XML database, CDB. The purpose of this API to provide a read and subscription API to CDB.

CDB owns and stores the configuration data and the user of the API wants to read that configuration data and also get notified when someone through either NETCONF, the CLI, the Web UI, or MAAPI modifies the data so that the application can re-read the configuration data and act accordingly.

Paths

In the C lib a path is a string. Assume the following YANG fragment:

         container hosts {
           list host {
             key name;
             leaf name {
               type string;
             }
             leaf domain {
               type string;
             }
             leaf defgw {
               type inet:ip-address;
             }
             container interfaces {
               list interface {
                 key name;
                 leaf name {
                   type string;
                 }
                 leaf ip {
                   type inet:ip-address;
                 }
                 leaf mask {
                   type inet:ip-address;
                 }
                 leaf enabled {
                   type boolean;
                 }
               }
             }
           }
         }

Furthermore assume the database is populated with the following data

             <hosts xmlns="http://acme.com/ns/hst/1.0">
                <host>
                  <name>buzz</name>
                  <domain>tail-f.com</domain>
                  <defgw>192.168.1.1</defgw>
                  <interfaces>
                    <interface>
                      <name>eth0</name>
                      <ip>192.168.1.61</ip>
                      <mask>255.255.255.0</mask>
                      <enabled>true</enabled>
                    </interface>
                    <interface>
                      <name>eth1</name>
                      <ip>10.77.1.44</ip>
                      <mask>255.255.0.0</mask>
                      <enabled>false</enabled>
                    </interface>
                  </interfaces>
                </host>
              </hosts>

The format path "/hosts/host{buzz}/defgw" refers to the leaf element called defgw of the host whose key (name element) is buzz.

The format path "/hosts/host{buzz}/interfaces/interface{eth0}/ip" refers to the leaf element called "ip" in the "eth0" interface of the host called "buzz".

In the Erlang CDB and MAAPI interfaces we use ikeypath() lists instead to address individual objects in the XML tree. The IkeyPath is backwards, thus the two above paths are expressed as

   [defgw, {<<"buzz">>}, host, [NS|hosts]]
   [ip, {<<"eth0">>}, interface, interfaces, {<<"buzz">>}, host, [NS|hosts]]

It is possible loop through all entries in a list as in:

   N = econfd_cdb:num_instances(CDB, [host,[NS|hosts]]),
   lists:map(fun(I) ->
               econfd_cdb:get_elem(CDB, [defgw,[I],host,[NS|hosts]]), .......
             end, lists:seq(0, N-1))
   

Thus in the list with length N [Index] is an implicit key during the life of a CDB read session.

Data Types

cdb_sess()

cdb_sess() = #cdb_session{}

A datastructure which is used as a handle to all the of the access functions

dbtype()

dbtype() = 1 | 2 | 3 | 4

When we open CDB sessions we must choose which database to read or write from/to. These ints are defined in econfd.hrl

err()

err() = {error, {integer(), binary()}} | {error, closed}

Errors can be either

• {error, Ecode::integer(), Reason::binary()} where Ecode is one of the error codes defined in econfd_errors.hrl, and Reason is (possibly empty) textual description
• {error, closed} if the socket gets closed

sub_ns()

sub_ns() = econfd:namespace() | ''

A namespace or use '' as wildcard (any namespace)

sub_type()

sub_type() = 1 | 2 | 3

Subscription type

• ?CDB_SUB_RUNNING - commit subscription.
• ?CDB_SUB_RUNNING_TWOPHASE - two phase subscription, i.e. notification will be received for prepare, commit, and possibly abort.
• ?CDB_SUB_OPERATIONAL - subscription for changes to CDB operational data.

subscription_sync_type()

subscription_sync_type() = 1 | 2 | 3 | 4

Return value from the fun passed to wait/3, indicating what to do with further notifications coming from this transaction. These ints are defined in econfd.hrl

Function Index

cd/2	Change the context node of the session.
close/1	End the session and close the socket.
connect/0	Equivalent to connect({127, 0, 0, 1}).
connect/1	Equivalent to connect(Address, 4565).
connect/2	Equivalent to connect(Address, Port, <<"econfd self()">>).
connect/3	Connect to CDB on the host with address Address:Port.
create/2	Only for CDB operational data: Create the element denoted by IKP.
delete/2	Only for CDB operational data: Delete the element denoted by IKP.
diff_iterate/5	Iterate over changes in CDB after a subscription triggers.
end_session/1	Terminate the session.
exists/2	Checks existense of an object.
get_case/3	Returns the current case for a choice.
get_elem/2	Read an element.
get_modifications_cli/2	Equivalent to get_modifications_cli(CDB, Point, 0).
get_modifications_cli/3	Return Return a string with the CLI commands that corresponds to the changes that triggered subscription.
get_object/2	Returns all the values in a container or list entry.
get_objects/4	Returns all the values for NumEntries list entries.
get_phase/1	Get CDB start-phase.
get_txid/1	Get CDB transaction id.
get_values/3	Returns the values for the leafs that have the "value" 'not_found' in the Values list.
index/2	Returns the position (starting at 0) of the list entry in path.
new_session/2	Initiate a new session using the socket returned by connect().
new_session/3	Initiate a new session using the socket returned by connect(), with detailed control via the Flags argument.
next_index/2	Returns the position (starting at 0) of the list entry after the given path (which can be non-existing, and if multiple keys the last keys can be '*').
num_instances/2	Returns the number of entries in a list.
set_case/4	Only for CDB operational data: Set the case for a choice.
set_elem/3	Only for CDB operational data: Write Value into CDB.
set_elem2/3	Only for CDB operational data: Write ValueBin into CDB.
set_object/3	Only for CDB operational data: Write an entire object, i.e.
set_values/3	Only for CDB operational data: Write a list of tagged values.
subscribe/3	Equivalent to subscribe(CDB, Prio, '', MatchKeyString).
subscribe/4	Set up a CDB configuration subscription.
subscribe/5	Equivalent to subscribe(CDB, Type, 0, Prio, Ns, MatchKeyString).
subscribe/6	Generalized subscription.
subscribe_done/1	After a subscriber is done with all subscriptions and ready to receive updates this subscribe_done/1 must be called.
subscribe_session/1	Initialize a subscription socket.
trigger_oper_subscriptions/1	Equivalent to trigger_oper_subscriptions(Socket, all).
trigger_oper_subscriptions/2	Equivalent to trigger_oper_subscriptions(Socket, SubPoints, 0).
trigger_oper_subscriptions/3	Trigger CDB operational subscribers as if an update in oper data had been done.
trigger_subscriptions/1	Equivalent to trigger_subscriptions(Socket, all).
trigger_subscriptions/2	Trigger CDB subscribers as if an update in the configuration had been done.
wait/3	Wait for subscription events.
wait_start/1	Wait for CDB to become available (reach start-phase one).

Function Details

cd/2

Change the context node of the session.

Note that this function can not be used as an existence test.

close/1

End the session and close the socket.

connect/0

Equivalent to connect({127, 0, 0, 1}).

connect/1

Equivalent to connect(Address, 4565).

connect/2

Equivalent to connect(Address, Port, <<"econfd self()">>).

connect/3

Connect to CDB on the host with address Address:Port.

If the port is changed it must also be changed in confd.conf A call to cdb_connect() is typically followed by a call to either new_session() for a reading session or a call to subscribe_session() for a subscription socket or calls to any of the write API functions for a data socket. ClientName is a string which confd will use as an identifier when e.g. reporting status.

create/2

Only for CDB operational data: Create the element denoted by IKP.

delete/2

Only for CDB operational data: Delete the element denoted by IKP.

diff_iterate/5

Iterate over changes in CDB after a subscription triggers.

This function can be called from within the fun passed to wait/3. When called it will invoke Fun for each change that matched the Point. If Flags is ?CDB_ITER_WANT_PREV, OldValue will be the previous value (if available). When OldValue or Value is not available (or requested) they will be the atom 'undefined'. When Op == ?MOP_MOVED_AFTER (only for "ordered-by user" list entry), Value == {} means that the entry was moved first in the list, otherwise Value is a econfd:key() tuple that identifies the entry it was moved after.

end_session/1

Terminate the session.

This releases the lock on CDB which is active during a read session. Returns a socket that can be re-used in new_session/2 We use connect() to establish a read socket to CDB. When the socket is closed, the read session is ended. We can reuse the same socket for another read session, but we must then end the session and create another session using new_session/2. %% While we have a live CDB read session, CDB is locked for writing. Thus all external entities trying to modify CDB are blocked as long as we have an open CDB read session. It is very important that we remember to either end_session() or close() once we have read what we wish to read.

exists/2

Checks existense of an object.

Leafs in the data model may be optional, and presence containers and list entries may or may not exist. This function checks whether a node exists in CDB, returning Int == 1 if it exists, Int == 0 if not.

get_case/3

Returns the current case for a choice.

get_elem/2

Read an element.

Note, the C interface has separate get functions for different types.

get_modifications_cli/2

Equivalent to get_modifications_cli(CDB, Point, 0).

get_modifications_cli/3

Return Return a string with the CLI commands that corresponds to the changes that triggered subscription.

get_object/2

Returns all the values in a container or list entry.

get_objects/4

Returns all the values for NumEntries list entries.

Starting at index StartIndex. The return value has one Erlang list for each YANG list entry, i.e. it is a list of NumEntries lists.

get_phase/1

Get CDB start-phase.

get_txid/1

Get CDB transaction id.

When we are a cdb client, and ConfD restarts, we can use this function to retrieve the last CDB transaction id. If it the same as earlier we don't need re-read the CDB data. This is also useful when we're a CDB client in a HA setup.

get_values/3

Returns the values for the leafs that have the "value" 'not_found' in the Values list.

This can be used to read an arbitrary set of sub-elements of a container or list entry. The return value is a list of the same length as Values, i.e. the requested leafs are in the same position in the returned list as in the Values argument. The elements in the returned list are always "canonical" though, i.e. of the form econfd:tagval().

index/2

Returns the position (starting at 0) of the list entry in path.

new_session/2

Initiate a new session using the socket returned by connect().

new_session/3

Initiate a new session using the socket returned by connect(), with detailed control via the Flags argument.

next_index/2

Returns the position (starting at 0) of the list entry after the given path (which can be non-existing, and if multiple keys the last keys can be '*').

num_instances/2

Returns the number of entries in a list.

set_case/4

Only for CDB operational data: Set the case for a choice.

set_elem/3

Only for CDB operational data: Write Value into CDB.

set_elem2/3

Only for CDB operational data: Write ValueBin into CDB. ValueBin is the textual value representation.

set_object/3

Only for CDB operational data: Write an entire object, i.e. YANG list entry or container.

set_values/3

Only for CDB operational data: Write a list of tagged values.

This function is an alternative to set_object/3, and allows for writing more complex structures (e.g. multiple entries in a list).

subscribe/3

Equivalent to subscribe(CDB, Prio, '', MatchKeyString).

subscribe/4

Set up a CDB configuration subscription.

A CDB subscription means that we are notified when CDB changes. We can have multiple subscription points. Each subscription point is defined through a path corresponding to the paths we use for read operations, however they are in string form and allow formats that aren't possible in a proper ikeypath(). It is possible to indicate namespaces in the path with a prefix notation (see last example) - this is only necessary if there are multiple elements with the same name (in different namespaces) at some level in the path, though.

We can subscribe either to specific leaf elements or entire subtrees. Subscribing to list entries can be done using fully qualified paths, or tagpaths to match multiple entries. A path which isn't a leaf element automatically matches the subtree below that path. When specifying keys to a list entry it is possible to use the wildcard character * which will match any key value.

Some examples:

• /hosts

  Means that we subscribe to any changes in the subtree - rooted at "/hosts". This includes additions or removals of "host" entries as well as changes to already existing "host" entries.

• /hosts/host{www}/interfaces/interface{eth0}/ip

  Means we are notified when host "www" changes its IP address on "eth0".

• /hosts/host/interfaces/interface/ip

  Means we are notified when any host changes any of its IP addresses.

• /hosts/host/interfaces

  Means we are notified when either an interface is added/removed or when an individual leaf element in an existing interface is changed.

• /hosts/host/types:data

  Means we are notified when any host changes the contents of its "data" element, where "data" is an element from a namespace with the prefix "types". The prefix is normally not necessary, see above.

The priority value is an integer. When CDB is changed, the change is performed inside a transaction. Either a commit operation from the CLI or a candidate-commit operation in NETCONF means that the running database is changed. These changes occur inside a ConfD transaction. CDB will handle the subscriptions in lock-step priority order. First all subscribers at the lowest priority are handled, once they all have synchronized via the return value from the fun passed to wait/3, the next set - at the next priority level - is handled by CDB.

Operational and configuration subscriptions can be done on the same socket, but in that case the notifications may be arbitrarily interleaved, including operational notifications arriving between different configuration notifications for the same transaction. If this is a problem, use separate sessions for operational and configuration subscriptions.

The namespace argument specifies the toplevel namespace, i.e. the namespace for the first element in the path. The namespace is optional, 0 can be used as "don't care" value.

subscribe() returns a subscription point which is an integer. This integer value is used later in wait/3 to identify this particular subscription.

subscribe/5

Equivalent to subscribe(CDB, Type, 0, Prio, Ns, MatchKeyString).

subscribe/6

Generalized subscription.

Where Type is one of

• ?CDB_SUB_RUNNING - traditional commit subscription, same as subscribe/4.
• ?CDB_SUB_RUNNING_TWOPHASE - two phase subscription, i.e. notification will be received for prepare, commit, and possibly abort.
• ?CDB_SUB_OPERATIONAL - subscription for changes to CDB operational data.

Flags is either 0 or:

• ?CDB_SUB_WANT_ABORT_ON_ABORT - normally if a subscriber is the one to abort a transaction it will not receive an abort notification. This flags means that this subscriber wants an abort notification even if it originated the abort.

subscribe_done/1

After a subscriber is done with all subscriptions and ready to receive updates this subscribe_done/1 must be called. Until it is no notifications will be delivered.

subscribe_session/1

Initialize a subscription socket.

This is a socket that is used to receive notifications about updates to the database. A subscription socket is used in the subscribe() function.

trigger_oper_subscriptions/1

Equivalent to trigger_oper_subscriptions(Socket, all).

trigger_oper_subscriptions/2

Equivalent to trigger_oper_subscriptions(Socket, SubPoints, 0).

trigger_oper_subscriptions/3

Trigger CDB operational subscribers as if an update in oper data had been done.

Flags can be given as ?CDB_LOCK_WAIT to have the call wait until the subscription lock becomes available, otherwise it should be 0.

trigger_subscriptions/1

Equivalent to trigger_subscriptions(Socket, all).

trigger_subscriptions/2

Trigger CDB subscribers as if an update in the configuration had been done.

wait/3

Wait for subscription events.

The fun will be given a list of the subscription points that triggered, and in the arity-3 case also Type and Flags for the notification. There can be several points if we have issued several subscriptions at the same priority.

Type is one of:

• ?CDB_SUB_PREPARE - notification for the prepare phase
• ?CDB_SUB_COMMIT - notification for the commit phase
• ?CDB_SUB_ABORT - notification for abort when prepare failed
• ?CDB_SUB_OPER - notification for changes to CDB operational data

Flags is the 'bor' of zero or more of:

• ?CDB_SUB_FLAG_IS_LAST - the last notification of its type for this session
• ?CDB_SUB_FLAG_TRIGGER - the notification was artificially triggered
• ?CDB_SUB_FLAG_REVERT - the notification is due to revert of a confirmed commit
• ?CDB_SUB_FLAG_HA_SYNC - the cause of the subscription notification is initial synchronization of a HA slave from CDB on the master.
• ?CDB_SUB_FLAG_HA_IS_SLAVE - the system is currently in HA slave mode.

The fun can return the atom 'close' if we wish to close the socket and return from wait/3. Otherwise there are three different types of synchronization replies the application can use as return values from either the arity-1 or the arity-3 fun:

• ?CDB_DONE_PRIORITY This means that the application has acted on the subscription notification and CDB can continue to deliver further notifications.
• ?CDB_DONE_SOCKET This means that we are done. But regardless of priority, CDB shall not send any further notifications to us on our socket that are related to the currently executing transaction.
• ?CDB_DONE_TRANSACTION This means that CDB should not send any further notifications to any subscribers - including ourselves - related to the currently executing transaction.
• ?CDB_DONE_OPERATIONAL This should be used when a subscription notification for operational data has been read. It is the only type that should be used in this case, since the operational data does not have transactions and the notifications do not have priorities.

Finally the arity-3 fun can, when Type == ?CDB_SUB_PREPARE, return an error either as {error, binary()} or as {error, #confd_error{}} ({error, tuple()} is only for internal ConfD/NCS use). This will cause the commit of the current transaction to be aborted.

CDB is locked for writing while config subscriptions are delivered.

When wait/3 returns {error, timeout} the connection (and its subscriptions) is still active and the application needs to call wait/3 again. But if wait/3 returns ok or {error, Reason} the connection to ConfD is closed and all subscription points associated with it are cleared.

wait_start/1

Wait for CDB to become available (reach start-phase one).

---

Generated by EDoc