Review Board 1.7.16

astdb: Allow clustering of the Asterisk Database between multiple Asterisk servers

Review Request #4490 - Created March 17, 2015 and updated

Matt Jordan
As described on the asterisk-dev mailing list [1], I got some inspiration from seeing Kamailio's htable implementation, and thought a similar mechanism would work for the Asterisk Database. This patch is the result.

This patch provides a mechanism to mark families within the AstDB as "shared." The marking of a family as shared is independent of the existance of the family, and is independent of the updates already made to the family. Shared families are subject to distribution with other Asterisk instances, as well as subject to updates from other Asterisk instances. Two strategies for sharing are implemented:

* Global: A 'global' shared family shares the family/key space with all other Asterisk instances. Say we have shared family 'foo', and we have two Asterisk instances. Say the first Asterisk instance (ast1) updates a key in family 'foo' to the following:

    /foo/key = bar

The second Asterisk instance (ast2) would then receive an update in its AstDB:

    /foo/key = bar

If ast2 later updates the same key in its local AstDB to 'foobar', ast1 will receive a notification to update the same key in its AstDB:

    /foo/key = foobar
    /foo/key = foobar

* Unique: A 'unique' shared family shares its values with other Asterisk instances, however, updates from other Asterisk instances are placed in unique families in the local AstDB for each Asterisk instance. Again, say we have shared family 'foo', and we have two Asterisk instances - ast1 and ast2. ast1 has an EID of 11:11:11:11:11:11, while ast2 has an EID of ff:ff:ff:ff:ff:ff. Say ast1 updates a key in family 'foo':

    /foo/key = bar

ast2 would receive the update for family 'foo', but instead of updating its local copy, it would instead store the value in a new family for ast1 corresponding to its EID:

    /11:11:11:11:11:11/foo/key = bar

If ast2 later updates the same ky in its local AstDB to 'foobar', the received value from ast1 will not be updated. However, ast1 will receive the update, and store the value in a new family for ast2 corresponding to its EID:

    /foo/key = foobar
    /11:11:11:11:11:11/foo/key = bar
    /foo/key = bar
    /ff:ff:ff:ff:ff:ff/foo/key = foobar

In order to manipulate shared families, two new dialplan functions have been added, DB_SHARED and DB_SHARED_EXISTS. DB_SHARED allows for creation of a shared family, as well as deletion, while DB_SHARED_EXISTS returns whether or not a family is shared:
  same => n,Set(DB_SHARED(put,global)=foo)      ; share family 'foo' globally
  same => n,Set(DB_SHARED(put,unique)=foobar)   ; share family 'foobar' uniquely
  same => n,NoOp(${DB_SHARED_EXISTS(foo)})      ; returns '1'
  same => n,Set(DB_SHARED(delete)=foo)          ; remove shared family status for 'foo'

CLI commands were also added to create/delete shared families, and the output of 'database show|showkey' updated to show the shared status of a family/key/value tuple.

Finally, a mechanism for sharing AstDB information was added to the PJSIP stack's res_pjsip_publish_asterisk. This includes a new event type, 'asterisk-db', which contains the values being created/deleted. Necessary configuration parameters were added to the existing configuration objects that support inbound/outbound PUBLISH support. An example of a PUBLISH request with the new event type is shown below:

PUBLISH sip:ast1@ SIP/2.0
Via: SIP/2.0/UDP;rport;branch=z9hG4bKPj1eb182a7-a0aa-4d73-995d-d2ad4b096db2
From: <sip:ast1@>;tag=7b294642-06ae-4ecf-8637-db8ba2dc4397
To: <sip:ast1@>
Call-ID: b9463adc-e364-440d-8ce1-842372813b08
CSeq: 48111 PUBLISH
Event: asterisk-db
Expires: 3600
Max-Forwards: 70
User-Agent: Asterisk PBX SVN-mjordan-trunk-astdb-cluster-URL:-r432916M-/trunk
Content-Type: application/json
Content-Length:   156


As a note on the power of the frameworks in Asterisk 13 - in this case, both Stasis and PJSIP - the vast bulk of this was written on two plane flights, plus a weekend or so of test writing and cleanup.

Existing AstDB tests execute successfully, as do the existing PJSIP PUBLISH tests. In addition:

* Unit tests were written (included in this review) that verify the API additions to the AstDB. This includes:
  - Verification of creation/delation of shared families
  - Verification that creating/deleting an AstDB entry in a shared family publishes the correct Stasis message
  - Verification that all keys/values in all shared families can be published via a 'refresh'

* Asterisk Test Suite tests for the PJSIP PUBLISH distribution of the AstDB information are available at:
Description From Last Updated Status
Review request changed
Updated (April 5, 2015, 9:22 p.m.)
Resolved Mark's findings.
Posted (April 8, 2015, 1:03 p.m.)
The only things I can think of that are issues here are based on theoretical usage of shared DB families, especially global ones.

Say that someone is sharing /foo/key between Asterisk 1 and Asterisk 2. A user on Asterisk 1 sets /foo/key = bar at the same time that a user on Asterisk 2 sets /foo/key = baz. What may happen is that the local Asterisk boxes will set the values locally and then publish the updated values near-simultaneously to the other Asterisk box. The result may be that they both have /foo/key = bar, they both might have /foo/key = baz, or Asterisk 1 may end up with /foo/key = baz and Asterisk 2 ends up with /foo/key = bar. Essentially, there is nothing in place to guarantee the synchronization of globally shared values.

So what's the best way to deal with this? I can think of several answers:
* The AstDB may not be the right tool for this use case and you should be using a key-value store that is built for this instead.
* You may be able to satisfy your use case with unique shared keys instead of global shared keys.
* We may want to make global shared keys one-way. In other words, there is an "owner" of the key and "listeners" for changes in the key's value. Listeners on a global shared key cannot update their local DB with new values; only the owner can push new values to it. Listeners on a global shared key cannot share the value with other listeners; only owners may push changes to listeners.

While I'm thinking about it, there's also the possibility that the underlying AstDB implementation could be replaced with a key-value store that has the concept of replication built into it. If that were done, then presumably, there would be no need to involve Stasis or SIP PUBLISH in the process of sharing values between Asterisk boxes. runs on a server provided by Digium, Inc. and uses bandwidth donated to the open source Asterisk community by API Digital Communications in Huntsville, AL USA.
Please report problems with this site to