.. -*- mode: rst -*-

.. _architecture-config-spec:

The Literal Configuration Specification
=======================================

Literal configuration specifications are served to clients by the
Bcfg2 server. This is a differentiating factor for Bcfg2; all other
major configuration management systems use a non-literal configuration
specification. That is, the clients receive a symbolic configuration that
they process to implement target states. We took the literal approach
for a few reasons:

* A small list of configuration element types can be defined, each of
  which can have a set of defined semantics. This allows the server to
  have a well-formed model of client-side operations. Without a static
  lexicon with defined semantics, this isn't possible. This allows the
  server, for example, to record the update of a package as a coherent
  event.
* Literal configurations do not require client-side processing. Removing
  client-side processing reduces the critical footprint of the tool.
  That is, the Bcfg2 client (and the tools it calls) need to be
  functional, but the rest of the system can be in any state. Yet,
  the client will receive a correct configuration.
* Having static, defined element semantics also requires that all
  operations be defined and implemented in advance. The implementation
  can maximize reliability and robustness. In more ad-hoc setups, these
  operations aren't necessarily safely implemented.

The Structure of Specifications
-------------------------------

Configuration specifications contain some number of clauses. Two types
of clauses exist. Bundles are groups of inter-dependent configuration
entities. The purpose of bundles is to encode installation-time
dependencies such that all new configuration is properly activated
during reconfiguration operations. That is, if a daemon configuration
file is changed, its daemon should be restarted. Another example of
bundle usage is the reconfiguration of a software package. If a package
contains a default configuration file, but it gets overwritten by an
environment-specific one, then that updated configuration file should
survive package upgrade. The purpose of bundles is to describe services,
or reconfigured software packages. Independent clauses contain groups
of configuration entities that aren't related in any way. This provides a
convenient mechanism that can be used for bulk installations of software.

Each of these clauses contains some number of configuration entities. A
number of configuration entities exist including Path, Package, Service,
etc. Each of these correspond to the obvious system item. Configuration
specifications can get quite large; many systems have specifications
that top one megabyte in size. An example of one is included in an
appendix. These configurations can be written by hand, or generated by
the server.