1 files changed, 54 insertions, 0 deletions
diff --git a/doc/architecture/config-spec.txt b/doc/architecture/config-spec.txt
new file mode 100644
index 000000000..57b131318
--- /dev/null
+++ b/doc/architecture/config-spec.txt
@@ -0,0 +1,54 @@
+.. -*- 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.