A generator is a module, loaded into bcfg2's address space, that can
be called to produce configuration data for clients. The code contains
can do anything, so any configuration pattern can be modeled. These
are useful for a variety of tasks; we currently use this interface to
define all of our sources of configuration logic. While this construct
was available in bcfg1, it suffered from a variety of issues, mainly
related to performance. The new API provides for high enough speed
execution that the generator API is the sole provider of configuration
data to the bcfg2 server. 

Several generators have been implemented in bcfg2:
Cfg: A basic configuration file repository
SSHBase: A ssh key management system
Pkgmgr: Provides information about available software
Svcmgr: Provides information about available services, and activations
Debconf: Generator debconf settings based on probed client data

Any of these generators can be enabled in bcfg2.conf, and custom
generators can similarly be added. 

Generators are during the client configuration process at two
times. First, generators provide client-side probes. These can be used
to determine local client state where appropriate. Generators can
provide a list of probes for a client to execute. The data generated
by this client execution is routed back to the source generator, which
can then use this data to generate the client configuration. 

The second function is to provide explicit values for the elements of
a client configuration. This function is used in the following way:

When a client requests its configuration, the bcfg2 daemon queries all
structuring agents for pertinent configurations. In general, this
means that all bundles and base configuration data for the appropriate
image are constructed. At this point, all of these are abstract, that
is, all entities contain name and type attributes, but don't contain
versions, or explicit file contents or status. Generators are queried
for individual configuration elements, of the form, which version of
package zsh should be installed on client X. 

Finding the generator responsible for a configuration entity has two
steps. First, each generator has a dispatch table (called
generator.__provides__) This dispatch table has a key for each type of
configuration element it handles, which in turn has keys for
particular instances of those types. For example, the generator that
handled configuration file /etc/ssh/sshd_config would have the
following dispatch table entry:
self.__provides__['ConfigFile']['/etc/ssh/sshd_config']
The value of this key is a function that can be called to bind in
configuration elements. (like version, owner, permissions, or file
data) 

Generators can be activated in other ways, but i would just as soon
not admit it in public. 

Probes can be created in generators to discover information about
clients. These xml elements look like:
<Probe source='my-generator' name='test1' interpreter='/bin/sh'>
hostname</Probe>

A generator can create as many of these as needed. Bcfg2 will query
for these by calling a generator's GetProbes method. By default, this
function returns an empty list, but can return an arbitrary number of
probe elements. 

These probes are forwarded to the client, where they are
executed. Output is collected and sent back to the bcfg2 server. the
source attribute is used to determine which data belongs to which
generator, and the AcceptProbeData method is called for each probe
result belonging to the generator. This data may then be used in
constructing configuration elements for the client. 

There is a generator base class that provides skeleton methods, which
custom generators should subclass. It is named
Bcfg2.Server.Generator.Generator.