This document will introduce you to the concepts and vocabulary of Verdad. Please read it before any other document.
Verdad is a system for managing configuration data about complex systems. If you are familiar with Cricket, it's like a turbo-charged version of the Cricket config tree.
Verdad is just a place to put information. Verdad does not control things. Verdad is not in charge of writing config files.
Scripts that rely on Verdad to decide what to do control things and write config files. The distinction is important but subtle.
As it is a place to put information, you can think of Verdad simply a database. But unlike most databases, Verdad keeps a history of all the changes made to the data it holds. Also, unlike other databases, the nature of the data in it is determined at runtime, both by the producers of data (i.e. the people and scripts that add data), and by the consumers of the data. There is no rigid schema controlling what data does and does not fit Verdad.
The final difference between Verdad and other databases is that it implements a style of inheritance that makes it easy to centralize configuration information that might be repeated in other databases in a small number of items. Centralizing this configuration information results in smaller databases, and less chance of unwanted divergence when managing a complex system.
Here is some of the kind of information Verdad is intended to handle:
Verdad is not intended to handle ongoing statistical data resulting from the operation of the system. Verdad could clearly keep track of what systems should be polled, and could help a user interface component navigate the collected data, but the data itself would not be appropriate for Verdad.
Verdad consists of a Perl API, a database, a web interface, and some command line tools.
Verdad stores it's data in a SQL database, which is currently implemented with MySql. However, because it implements features that SQL databases don't, all access to Verdad's data happens either via the Perl API, or by making queries via HTTP to the web interface for Verdad. It is very difficult, and not recommended, to interact with the Verdad database via SQL.
The web interface is implemented as a set of Perl programs that can run under a webserver using the CGI. For speed, they are usually run instead under Apache's mod_perl using Apache::Registry.
The main command line tool is named ``verdad''. It allows users and scripts to add, delete, and edit items.
Scripts which are not strictly part of Verdad use the HTTP interface and the Perl API to get data from Verdad. They do work based on this data that in turn manages the complex system. It bears repeating here: Verdad is a place to store information. Verdad is not a system which directly controls other systems.
See transaction.
The history of an item is a list of who has done what to it when. This is a common feature of configuration management systems. It helps isolate what changes happened when, and why.
The tag is is used to indicate to Verdad which items inherit from which other ones. You can find out more about how Verdad implements inheritance in the document devoted to it.
The rule used to decide how a value inherited from an ancestor item will be applied to the current item. Inheritance policies can be specified on a per-tag basis.
An item is a collection of tags and values. Each item has an item name. All of the item names in an entire Verdad database must be unique.
A tag is the thing to the left of the equals sign or colon. Of course, since both the equal sign and the colon are optional, perhaps another explanation would be helpful. Tags are descriptions of the data, which programs will use later to find the bit of data they want. For example, if you wanted to store an IP address in an item and later wanted the dhcpgen program to find it, you'd use a tag named ip, then write your dhcpgen so that it looks for a tag named ip.
Every time a write is committed to the Verdad database, all of the changes related to that write are assigned a unique, monotonically increasing number. For instance, if you check out one item and break it into two, one which inherits from the other, then check back in both items (one old one and one new one), you've just made a transaction. You can use Verdad's web interface to see what items were changed together during a transaction. You can find transaction numbers in the history view of an item.
Transactions numbers are normally called ``Change Numbers'' in the user interface, because it's a more descriptive name. The API and the database itself refer to them as transactions.
The value is the thing to the right of the equal sign. Each tag can have one or mote values associated with it. If a tag appears multiple times in an item, then it has multiple values. It's up the person or program that uses the data to decide what to do with the list. Verdad assumes order is important and preserves it.
Jeff R. Allen <jra@nella.org>