This topic describes how application and system configuration works in Legato AF.

Device config data is vital for most apps. Seldom are all devices in an application identical. Usually, there's some kind of customization on each device: it may be a complex set of user preferences, or it may be just a simple node name. Regardless of the device's customization, the device needs to be:

stored somewhere it can be retrieved quickly
easy to modify programmatically from within the device application code
easy to view and modify remotely via generic network or managed portal service
protected from:
- malicious snooping and vandalism
- multi-threaded race conditions
- untimely device reset or power loss

Tree Structure

Config data is stored in a tree structure, where each node is made up of a stem or a leaf. Stem nodes can contain any number of child nodes, each with its own name. Leaf nodes can either be empty or contain data.

       +tree
           |
           +--stem
           |   |
           |   +--leaf (value)
           |
           +-stem
           |  |
           |  +--leaf (value)
           |  |
           |  +--leaf (value)
           |
           +--stem
               |
               +stem
               |  |
               |  +leaf (value)
               |  |
               |  +stem
               |    |
               |    +stem
               |       |
               |       +leaf (value)
               |
               +leaf (value)~

This tree structure allows config data items to be uniquely identified using path names, much like file system paths, which makes it much easier to access config data via HTTP, SNMP, OMA-DM, and other protocols. It also allows the config database to be explored using tree walking algorithms and tools.

Transactions

Config data can be shared by multiple processes and threads. This can sometimes result in race conditions that can threaten data integrity. E.g., if threads A and B both use data fields X and Y, it could be bad if thread A interrupts thread B to read those fields just after thread B has updated field X and is about to update field Y to be consistent with the new value of field X.

A possible reset or power loss may occur at any time, and we must be sure that would not corrupt the config data. For example, if power fails just after field X has been updated, but before field Y gets updated to match the new value of field X, then the config data could be in an invalid state. Transactions are used to prevent these sorts of problems.

Before a change can be made to config data, a write transaction must be started. All changes are made in the context of such a transaction, and when the changes are complete, the transaction can be "committed". If a fault prevents the entire set of changes from being applied on commit, or if the transaction is canceled before it is committed, then none of that transaction's changes will be applied.

Transactions can also be started for reading only. A write transaction will be allowed to start while there is a read transaction in progress. But the commit process will block write transactions until the read transactions have finished. This ensures that anyone reading config data fields will see only field values that are consistent.

To prevent denial of service problems (either accidental or malicious), transactions have a limited lifetime. If a transaction remains open for too long, it will be automatically terminated; the configuration database will drop its connection to the offending client.

Config Data Growth

Config structure will change over time as your app is developed and new features are added. Config tree changes need to be managed in a way that supports the growth and the upgrades.

Recommended strategies when upgrading your app's tree:

Have newer software understand the config data structure used by previous versions of the software;
Never write to the config data unless settings are being changed;
When changing settings, write the config data using the newest format;
If both multiple versions of the same config data are found, use only the newest that is understood by the current running software;
If you are backing up the original config tree keep in mind the limited space requirements of the non-volatile memory, or the time and data cost of over-the-air bandwidth.

Software Updates and Roll-Back

When you update apps that use Config Trees, and the upgrade is done using the Software Update API:

the updated new system automatically inherits (copies) the trees from the old system.
if a roll-back happens, the updated system trees (possibly corrupted) are deleted, and the old system is restored (along with the old config trees in the same state as before the update).

Note: The update tool uses the Software Update API.

Config Change Notifications

Sometimes, action needs to be taken whenever a config data field changes value. The Config Tree API allows client software to register for notification when changes are committed to a particular branch of the config tree.

Access Control

Because the behavior of apps can be affected by the config data that they use, config data can be used as an attack vector for malicious software. As a result, access to config data must be strictly controlled when there is any possibility that malicious software may be allowed to run on a device.

The Config Tree system separates each apps' configuration data only allowing access to its own data.

See .adef requires section for details about setting permissions for your trees.