diff options
Diffstat (limited to 'doc/generators.xml')
| -rw-r--r-- | doc/generators.xml | 266 |
1 files changed, 0 insertions, 266 deletions
diff --git a/doc/generators.xml b/doc/generators.xml deleted file mode 100644 index 053c754e3..000000000 --- a/doc/generators.xml +++ /dev/null @@ -1,266 +0,0 @@ -<chapter> - <title>Generators</title> - - <para> - Generators are modules which are loaded by the Bcfg2 server, - based on directives in <filename>/etc/bcfg2.conf</filename>. They - provide concrete, fully-specified configuration entries for - clients. This chapter documents the function and usage of - generators bundled with Bcfg2 releases. It also describes the - interface used to communicate with generators; modeles - implementing this interface can provide configuration elements for - clients based on any representation or requirements that may - exist. - </para> - - <section> - <title>Bundled Generators</title> - - <para>This section describes the generators that come bundled with - Bcfg2. As a general rule, generators requiring more than one - configuration file will use a generator specific directory in the - configuration repository. - </para> - - <section> - <title>Cfg</title> - <para> - The Cfg generator provides a configuration file repository - that uses literal file contents to provide client-tailored - configuration file entries. The Cfg generator chooses which - data to provide for a given client based on the aspect-based - metadata system used for high-level client configuration. - </para> - <para> - The Cfg repository is structured much like the filesystem - hierarchy being configured. Each configuration file being - served has a corresponding directory in the configuration - repository. These directories have the same relative path as - the absolute path of the configuration file on the target - system. For example, if Cfg was serving data for the - configuration file <filename>/etc/services</filename>, then - its directory would be in the relative path - <filename>./etc/services</filename> inside of the Cfg - repository. - </para> - <para> - Inside of this file-specific directory, three types of files - may exist. Base files are complete instances of configuration - file. Deltas are differences between a base file and the - target file contents. Base files and deltas are tagged with - metadata specifiers, which describe which groups of clients - the fragment pertains to. Configuration files are constructed - by finding the most specific base file and applying any more - specific deltas. - </para> - <para> - Specifiers are embedded in fragment filenames. For example, in - the fragment <filename>services.C99_webserver</filename>, - "C99_webserver" is the specifier. This specifier applies to - the class (C) webserver with a priority of 99. Other metadata - categories which can be used include bundle (B), profile (P), - hostname (H), attribute (A), and image (I). These are ordered - from least to most specific: image, profile, class, bundle, - and hostname. Global files are the least specific. Priorities - are used as to break ties. - </para> - <para> - Info files, named <filename>:info</filename> are used to - specify target configuration file metadata, such as owner, - group and permissions. If no <filename>:info</filename> is - provided, targets are installed with default - information. Default metadata is root ownership, root group - memberships, and 0644 file permissions. - </para> - <example> - <title>Cfg generator :info files</title> - <programlisting> - owner:root - group:root - perms:0755 - </programlisting> - </example> - - <example> - <title>Cfg file repository example</title> - <programlisting> - $ ls - :info passwd passwd.C99_chiba-login - passwd.H_bio-debian passwd.H_cvstest passwd.H_foxtrot - passwd.H_reboot passwd.H_rudy2 passwd.C99_netserv - passwd.B99_tacacs-server.cat passwd.H_adenine - </programlisting> - </example> - - <para> - In the previous example, there exists files with each of the - characteristics mentioned above. All files ending in ".cat" - are deltas; ones with ".H_" are host specific files. There - exists a base file, a <filename>:info</filename> file, two - class-specified base files, and a bundle-specified base file. - </para> - </section> - - <section> - <title>The Scoped XML File Group: Servicemgr</title> - <para> - The generator Servicemgr uses files formatted similarly to the - metadata files. It - works based on a single file, which contains definitions - ordered by increasing specificity. - </para> - - <example> - <title><filename>services.xml</filename></title> - <programlisting> - <![CDATA[<Services> - <Class name='webserver'> - <Service status='on' name='httpd' port='80' protocol='tcp'> - <User address='0.0.0.0' mask='32'/> - </Service> - </Class> - <Host name='mailhost'> - <Service name='sendmail' status='on' protocol='tcp' port='80'> - <User address='0.0.0.0' mask='32'/> - </Service> - </Host> - <Host name='thai'> - <Service name='ssh' status='off'/> - </Host> - <Service name='ssh' status='on' protocol='tcp' port='22'/> - <Service name='ntp-server' status='on' /> -</Services>]]> - </programlisting> - </example> - - <para> - This set of service definitions is intrepreted in the - following way. Webservers run httpd, the host mailhost runs - sendmail, and all machines run ssh, and the ntp-server. - </para> - </section> - - </section> - - <section> - <title>The Generator API</title> - <para> - The Bcfg2 core has a well-formed API used to call - generators. This mechanism allows all stock generators to be - runtime selected; no stock generators are required. The - generator API has two main functions. The first is communication - to the Bcfg2 core: the list of entries a particular generator - can bind must be communicated to the core so that the proper - generator can be called. The second function is the actual - production of client-specific configuration element data; this - data is then included in client configurations. - </para> - - <para> - The inventory function is provided by a python dictionary, - called __provides__ in each generator object. This dictionary - has a key for each type of configuration entry (ConfigFile, - Package, Directory, SymLink, Service), whose value is a - dictionary indexed by configuration element name. For example, - the data path to information about the service "sshd" could be - reached at __provides__['Service']['sshd']. The value of each of - these keys is a function that can be called to bind - client-specific values to a configuration entry. This function - is used in the next section. - </para> - - <para> - The handler function located by the __provides__ dictionary is - called with a static API. The function prototype for each of - these handlers is: - </para> - - <example> - <title>The Generator handler API</title> - <programlisting> - def Handler(self, entry, metadata): - generator logic here - </programlisting> - </example> - - <para> - The data supplied upon handler invokation includes two - parts. The first is the entry. This is a ElementTree.Element - object, which already contains the configuration element type - (ie Service) and name. All other data is bound into this object - in this function. The range of data bound depends on the data - type. The other data provided to handlers is client metadata, - information about the current client, including hostname, image, - profile, classes and bundles. The metadata is typically used to - choose entry contents. - </para> - </section> - - <section> - <title>Writing a Generator</title> - <para> - Writing a generator is a fairly straightforward task. At a high - level, generators are instantiated by the Bcfg2 core, and then - used to provide configuration entry contents. This means that - the two points where control passes into a generator from Bcfg2 - are during initial object instantiation, and every time a - generator-provided configuration entry is bound. - </para> - - <para> - Currently, generators must be written in python. They can - perform arbitrary operations, hence, a generator could be - written that executed logic in another language, but this - functionality is currently not implemented. - </para> - - <example> - <title>Simple Generator</title> - <programlisting> - from socket import gethostbyname, gaierror - from syslog import syslog, LOG_ERR - from Bcfg2.Server.Generator import Generator, DirectoryBacked, SingleXMLFileBacked, GeneratorError - -class Chiba(Generator): - '''the Chiba generator builds the following files: - -> /etc/network/interfaces''' - - __name__ = 'Chiba' - __version__ = '$Id: Chiba.py 1.12 05/01/15 11:05:02-06:00 desai@topaz.mcs.anl.gov $' - __author__ = 'bcfg-dev@mcs.anl.gov' - __provides__ = {'ConfigFile':{}} - - def __init__(self, core, datastore): - Generator.__init__(self, core, datastore) - self.repo = DirectoryBacked(self.data, self.core.fam) - self.__provides__['ConfigFile']['/etc/network/interfaces'] = self.build_interfaces - - def build_interfaces(self, entry, metadata): - '''build network configs for clients''' - entry.attrib['owner'] = 'root' - entry.attrib['group'] = 'root' - entry.attrib['perms'] = '0644' - try: - myriaddr = gethostbyname("%s-myr" % metadata.hostname) - except gaierror: - syslog(LOG_ERR, "Failed to resolve %s-myr"% metadata.hostname) - raise GeneratorError, ("%s-myr" % metadata.hostname, 'lookup') - entry.text = self.repo.entries['interfaces-template'].data % myriaddr - </programlisting> - </example> - - <para> - Generators must subclass the Bcfg2.Server.Generator.Generator - class. Generator constructors must take two arguments: an - instance of a Bcfg2.Core object, and a location for a - datastore. __name__, __version__, __author__, and __provides__ - are used to describe what the generator is and how it - works. __provides__ describes a set of configuration entries - that can be provided by the generator, and a set of handlers - that can bind in the proper data. build_interfaces is an example - of a handler. It gets client metadata and an configuration entry - passed in, and binds data into entry as appropriate. - </para> - - </section> -</chapter>
\ No newline at end of file |