diff options
| -rw-r--r-- | doc/architecture.xml | 290 | ||||
| -rw-r--r-- | doc/deployment.xml | 2 | ||||
| -rw-r--r-- | doc/manual.xml | 5 | ||||
| -rw-r--r-- | doc/reports.xml | 33 | ||||
| -rw-r--r-- | doc/specs.xml | 58 |
5 files changed, 198 insertions, 190 deletions
diff --git a/doc/architecture.xml b/doc/architecture.xml index 7c54fca45..779b57611 100644 --- a/doc/architecture.xml +++ b/doc/architecture.xml @@ -110,100 +110,101 @@ <!-- <step>foo</step> --> <!-- </procedure> --> - <variablelist> - <varlistentry> - <term>Probe Execution</term> - <listitem> - <para>During the probe execution stage, the client connects to - the server and downloads a series of probes to execute. These - probes reveal local facts to the Bcfg2 server. For example, a - probe could discover the type of video card in a system. The - Bcfg2 client returns this data to the server, where it can - influence the client configuration generation - process. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Configuration Download and Inventory</term> - <listitem> - <para>The Bcfg2 client now downloads a configuration + <orderedlist> + <listitem> + <para>Probe Execution</para> + <para>During the probe execution stage, the client connects to + the server and downloads a series of probes to execute. These + probes reveal local facts to the Bcfg2 server. For example, a + probe could discover the type of video card in a system. The + Bcfg2 client returns this data to the server, where it can + influence the client configuration generation + process. + </para> + </listitem> + <listitem> + <para>Configuration Download and Inventory</para> + <para> + The Bcfg2 client now downloads a configuration specification from the Bcfg2 server. The configuration describes the complete target state of the machine. That is, all aspects of client configuration should be represented in this specification. For example, all software packages and services should be represented in the configuration - specification. </para> + specification. + </para> - <para>The client now performs a local system inventory. This + <para> + The client now performs a local system inventory. This process consists of verifying each entry present in the configuration specification. After this check is completed, heuristic checks for configuration not included in the configuration specification. We refer to this inventory process as 2-way validation, as first we verify that the client contains all configuration that is included in the - specification, then we check of the client has any extra + specification, then we check if the client has any extra configuration that isn't present. This provides a fairly - rigorous notion of client configuration congruence. </para> + rigorous notion of client configuration congruence. + </para> - <para>Once the 2-way verification process has been + <para> + Once the 2-way verification process has been performed, the client has built a list of all configuration entries that are out of spec. This list has two parts: specified configuration that is incorrect (or missing) and - unspecified configuration that should be removed.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>Configuration Update</term> - <listitem> - <para> - The client now attempts to update its configuration to - match the specification. Depending on options, changes may - not (or only partially) be performed. First, if extra - configuration correction is enabled, extra configuration can - be removed. Then the remaining changes are processed. The - Bcfg2 client loops while progress is made in the correction - of these incorrect configuration entries. This loop results - in the client being able to accomplish all it will be able - to during one execution. Once all entries are fixed, or no - progress is being made, the loop terminates. - </para> + unspecified configuration that should be removed. + </para> + </listitem> + <listitem> + <para>Configuration Update</para> + <para> + The client now attempts to update its configuration to + match the specification. Depending on options, changes may + not (or only partially) be performed. First, if extra + configuration correction is enabled, extra configuration can + be removed. Then the remaining changes are processed. The + Bcfg2 client loops while progress is made in the correction + of these incorrect configuration entries. This loop results + in the client being able to accomplish all it will be able + to during one execution. Once all entries are fixed, or no + progress is being made, the loop terminates. + </para> - <para> - Once all configuration changes that can be performed - have been, bundle dependencies are handled. Bundles - groupings result in two different behaviors. Entries are - assumed to be inter-dependant. To address this, the client - re-verifies each entry in any bundle containing an updates - configuration entry. Also, services contained in modified - bundles are restarted. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Statistics Upload</term> - <listitem> - <para>Once the reconfiguration process has concluded, the + <para> + Once all configuration changes that can be performed have + been, bundle dependencies are handled. Bundle groupings + result in two different behaviors. Contained entries are + assumed to be inter-dependant. To address this, the client + re-verifies each entry in any bundle containing an updates + configuration entry. Also, services contained in modified + bundles are restarted. + </para> + </listitem> + <listitem> + <para>Statistics Upload</para> + <para> + Once the reconfiguration process has concluded, the client reports information back to the server about the actions it performed during the reconfiguration process. Statistics function as a detailed return code from the client. The server stores statistics information. Information included in this statistics update - includes (but is not limited to):</para> + includes (but is not limited to): + </para> - <itemizedlist> - <listitem> - <para>Overall client status (clean/dirty)</para> - </listitem> - <listitem> - <para>List of modified configuration entries</para> - </listitem> - <listitem> - <para>List of uncorrectable configuration entries</para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - </variablelist> + <itemizedlist> + <listitem> + <para>Overall client status (clean/dirty)</para> + </listitem> + <listitem> + <para>List of modified configuration entries</para> + </listitem> + <listitem> + <para>List of uncorrectable configuration entries</para> + </listitem> + </itemizedlist> + </listitem> + </orderedlist> <section> <title>Architecture Abstraction</title> @@ -213,12 +214,12 @@ apt-get are both supported, allowing operation of Debian, Redhat, SUSE, and Mandriva systems. The client toolset is specified in the configuration specification. The client merely - includes a series of libraries while describe how to interact + includes a series of libraries which describe how to interact with the system tools on a particular platform. </para> <para> - Three of the libraries exist. There is the base set of + Three of the libraries exist. There is a base set of functions, which contain definitions describing how to perform POSIX operations. Support for configuration files, directories, and symlinks are included here. Two other @@ -259,9 +260,10 @@ <para> The Bcfg2 server takes information from two sources when generating client configuration specifications. The first is a - pool of metadata that describes clients as members of an aspect - based classing system. The other is a file system repository - that contains mappings from metadata to literal + pool of metadata that describes clients as members of an + aspect-based classing system. That is, clients are defined in + terms of aspects of their behavior. The other is a file system + repository that contains mappings from metadata to literal configuration. These are combined to form the literal configuration specifications for clients. </para> @@ -276,77 +278,71 @@ client. This process consists of the following steps: </para> - <variablelist> - <varlistentry> - <term>Metadata Lookup</term> - <listitem> - <para> - The server uses the client's IP address to initiate the - metadata lookup. This initial metadata consists of a - (profile, image) tuple. If the client already has - metadata registered, then it is used. If not, then - default values are used and stored for future use. - </para> - - <para> - This metadata tuple is expanded using some profile and - class definitions also included in the metadata. The end - result of this process is metadata consisting of - hostname, profile, image, a list of classes, a list of - attributes and a list of bundles. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Abstract Configuration Construction</term> - <listitem> - <para> - Once the server has the client metadata, it is used to - create an abstract configuration. An abstract - configuration contains all of the configuration elements - that will exist in the final specification without any - specifics. All entries will be typed (ie the tagname - will be one of Package, ConfigurationFile, Service, - Symlink, or Directory) and will include a name. These - configuration entries are grouped into bundles, which - document installation time interdependencies. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>Configuration Binding</term> - <listitem> - <para> - The abstract configuration determines the structure of - the client configuration, however, it doesn't contain - literal configuration information. After the abstract - configuration is created, each configuration entry must - be bound to a client-specific value. The Bcfg2 server - uses plugins to provide these client-specific bindings. - </para> + <orderedlist> + <listitem> + <para>Metadata Lookup</para> + <para> + The server uses the client's IP address to initiate the + metadata lookup. This initial metadata consists of a + (profile, image) tuple. If the client already has + metadata registered, then it is used. If not, then + default values are used and stored for future use. + </para> + + <para> + This metadata tuple is expanded using some profile and + class definitions also included in the metadata. The end + result of this process is metadata consisting of + hostname, profile, image, a list of classes, a list of + attributes and a list of bundles. + </para> + </listitem> + <listitem> + <para>Abstract Configuration Construction</para> + <para> + Once the server has the client metadata, it is used to + create an abstract configuration. An abstract + configuration contains all of the configuration elements + that will exist in the final specification without any + specifics. All entries will be typed (ie the tagname + will be one of Package, ConfigurationFile, Service, + Symlink, or Directory) and will include a name. These + configuration entries are grouped into bundles, which + document installation time interdependencies. + </para> + </listitem> + <listitem> + <para>Configuration Binding</para> + <para> + The abstract configuration determines the structure of + the client configuration, however, it doesn't contain + literal configuration information. After the abstract + configuration is created, each configuration entry must + be bound to a client-specific value. The Bcfg2 server + uses plugins to provide these client-specific bindings. + </para> - <para> - The Bcfg2 server core contains a dispatch table that - describes which plugins can handle requests of a - particular type. The responsible plugin is located - for each entry. It is called, passing in the - configuration entry and the client's metadata. The - behavior of plugins is explicitly undefined, so as to - allow maximum flexibility. The behaviors of the stock - plugins are documented elsewhere in this manual. - </para> + <para> + The Bcfg2 server core contains a dispatch table that + describes which plugins can handle requests of a + particular type. The responsible plugin is located + for each entry. It is called, passing in the + configuration entry and the client's metadata. The + behavior of plugins is explicitly undefined, so as to + allow maximum flexibility. The behaviors of the stock + plugins are documented elsewhere in this manual. + </para> - <para> - Once this binding process is completed, the server has a - literal, client-specific configuration - specification. This specification is complete and - comprehensive; the client doesn't need to process it at - all in order to use it. It also represents the totality - of the configuration specified for the client. - </para> - </listitem> - </varlistentry> - </variablelist> + <para> + Once this binding process is completed, the server has a + literal, client-specific configuration + specification. This specification is complete and + comprehensive; the client doesn't need to process it at + all in order to use it. It also represents the totality + of the configuration specified for the client. + </para> + </listitem> + </orderedlist> </section> </section> @@ -367,9 +363,11 @@ <para> 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 notion of + allows the server to have a well-formed model of client-side operations. Without a static lexicon with - defined semantics, this isn't possible. + defined semantics, this isn't possible. This allows the + server, for example, to record the update of a package as a + coherent event. </para> </listitem> <listitem> diff --git a/doc/deployment.xml b/doc/deployment.xml index 1114589d3..4c4cc9bf6 100644 --- a/doc/deployment.xml +++ b/doc/deployment.xml @@ -87,7 +87,7 @@ <title>An example application of bcfg2</title> <para> In my computing environment there are quite a diverse set of machines - and requirements for there operation. What this meant is that I needed + and requirements for their operation. What this meant was that I needed to devise a build system for machines that would allow me to easily customize the software and services on the machine while still being able to easily manage them and keep them secure. What I came up with diff --git a/doc/manual.xml b/doc/manual.xml index 878a104fb..6985085ad 100644 --- a/doc/manual.xml +++ b/doc/manual.xml @@ -63,6 +63,11 @@ <emphasis>fitness for a particular purpose</emphasis>. See the GNU General Public License for more details. </para> + <para> + Required software packages may require additional + terms. Please refer to these individual packages for more + information. + </para> </legalnotice> <revhistory> diff --git a/doc/reports.xml b/doc/reports.xml index 3913a9985..ce49597c9 100644 --- a/doc/reports.xml +++ b/doc/reports.xml @@ -40,19 +40,18 @@ <command>StatReports</command> gets the data it reports from a number of sources. <filename>Metadata/clients.xml</filename> contains information about if a host is currently pingable or - not, and a mapping of short hostnames to - FQDNs. <command>GenerateHostInfo</command> will be run + not. <command>GenerateHostInfo</command> will be run automatically by <command>StatReports</command> if the <filename>Metadata/clients.xml</filename> file is older than - 23.5 hours. This number is chosen, because it is likely an - administrator will recieve reports daily about the status of - hosts and if they had run BCFG the previous night. It is - possible to execute <command>GenerateHostInfo</command> to - update the <filename>Metadata/clients.xml</filename> file at any - interval via cron, but it does take some time to complete, so be - sure to give it a few minutes. This will only likely be of use - if your BCFG clients are set to update more often than nightly - and you would like reports after each run. + 23.5 hours. We chose this interval due to our normal use of + reports; clients run bcfg2, in general, once a day after which + reports are delivered to administrators. It is possible to + execute <command>GenerateHostInfo</command> to update the + <filename>Metadata/clients.xml</filename> file at any interval + via cron, but it does take some time to complete, so be sure to + give it a few minutes. This will only likely be of use if your + BCFG clients are set to update more often than nightly and you + would like reports after each run. </para> <para> @@ -60,7 +59,7 @@ <filename>statistics.xml</filename> file. This file is maintained by bcfgd, and is updated whenever a client updates, therefore is always up to date, and no - maintainence is required on this file. + maintainance is required on this file. </para> <para> @@ -97,7 +96,7 @@ <row><entry>Overview-Stats</entry> <entry> <para> - This report provides informatoin about a large number of + This report provides information about a large number of machines and their states. It is often found to be useful when the group of machines it is connected with is simply All Nodes, which gives an overall outlook on your @@ -230,10 +229,10 @@ </example> <para> - Once configured correctly, just wait for the e-mail or check - look at the output html files with a web browser. You can run - <command>StatReports</command> by hand if you would like - in order to try it out immediately. + Once configured correctly, just wait for the e-mail or view the + outputed html files with a web browser. You can run + <command>StatReports</command> by hand if you would like in + order to try it out immediately. </para> <mediaobject> diff --git a/doc/specs.xml b/doc/specs.xml index 4f4aa9f33..d1f61c10b 100644 --- a/doc/specs.xml +++ b/doc/specs.xml @@ -4,8 +4,8 @@ <para> The Bcfg2 specification is a set of directives that describe how hosts should be configured. This information is used to generate - client configurations. This section describes the steps taken in - during the composition of bcfg2 specifications. + client configurations. This section describes the steps taken + during the composition of bcfg2 specifications. </para> <orderedlist> @@ -50,15 +50,17 @@ <title>Interacting with Client Groups in Bcfg2</title> <para> - Bcfg2 uses an aspect based classing mechanism to describe - configuration patterns in its specifications. The Bcfg2 metadata + Bcfg2 uses an aspect-based classing mechanism to describe + configuration patterns in its specifications. Each class + describes particular aspects of client configurations. The Bcfg2 metadata mechanism has two types of information, client metadata and group metadata. Client metadata describes what top level group a - client is associated. Its configuration is derived from a + client is associated with. Its configuration is derived from a combination of its host information and this group. Group definitions describe groups in terms of what bundles they include and other groups they include. Groups have a set of - properties that describe how they can be used. + properties that describe how they can be used. (Starred values + are defaults) </para> <table> @@ -81,7 +83,7 @@ make configuration changes</entry><entry>(rh|debian|solaris)</entry></row> <row><entry>category</entry> - <entry>A group can only contain one instance of a group of + <entry>A group can only contain one instance of a group in any category. This provides the basis for representing groups which are conjugates of one another in a rigorous way. It also provides the basis for negation.</entry><entry>string</entry></row> @@ -91,7 +93,7 @@ </section> <para> - When a client's configuration is generated, its metadata is the + When a client's configuration is generated, its metadata is fetched. This includes a list of all groups recursively dereferenced, and all bundles included by those groups. This collection has already been processed using the group category @@ -99,7 +101,7 @@ included. This metadata is used throughout the rest of the configuration generation process; it defines the client's abstract configuration and specifies all literal contents of all - configuration entities. + configuration entities. </para> <section> @@ -269,10 +271,10 @@ <example> <title>Cfg/etc/passwd/</title> <programlisting> $ ls - :info passwd passwd.G99_chiba-login - passwd.H_bio-debian passwd.H_cvstest passwd.H_foxtrot - passwd.H_reboot passwd.H_rudy2 passwd.G98_netserv - passwd.G99_tacacs-server.cat passwd.H_adenine</programlisting> + passwd.H_adenine passwd passwd.G99_chiba + passwd.H_bio-debian passwd.H_cvstest passwd.H_foxtrot + passwd.H_reboot passwd.H_rudy2 passwd.G98_netserv + passwd.G99_tacacs-server.cat :info</programlisting> </example> <para> @@ -295,13 +297,13 @@ format to the files used by Base and Bundler, but with a few differences. First, each file has a priority. This allows the same entity to be served by multiple files. The priorities can - be used to disambiguate in the case that multiple files serve + be used to break ties in the case that multiple files serve data for the same package. The other difference is that automatic deriviation of package information from the file - attribute. The Pkgmgr has a set of regexes that can split - package names for several formats. The filenames are used to - construct installation URLs, and set several important fields - like package name and version. + attribute. The Pkgmgr has a set of regular expressions that + can split package names for several formats. The filenames are + used to construct installation URLs, and set several important + fields like package name and version. </para> <table> @@ -319,9 +321,11 @@ <entry>URL-style location of file repository (typically http)</entry></row> <row><entry>file</entry><entry>Package file name. Several other attributes (name, version, url) can be automatically - defined based on regexes definied in the Pkgmgr plugin.</entry></row> + defined based on regular expressions definied in the + Pkgmgr plugin.</entry></row> <row><entry>simplefile</entry><entry>Package file name. No - name parsing is performed, so no extra fields get set</entry></row> + name parsing is performed, so no extra fields get + set</entry></row> </tbody> </tgroup> </table> @@ -348,7 +352,8 @@ conditions as well. For example, the following declaration turns ssh on by default, disables it if the client is a part of group a, and reenables it if the client is a part of both - groups a and b. + groups a and b. Group nesting provides a conjunctive + function. </para> <example> @@ -436,7 +441,7 @@ <orderedlist> <listitem><para> - In this case, the target group is global, since we want + In this case, the target group is all clients, since we want this version of <filename>/etc/motd</filename>. As mentioned earlier, the global group is handled specially, so that all new clients, even newly created ones, are in it. @@ -458,7 +463,7 @@ </para></listitem> <listitem><para> Since this change is globally scoped, there are not any - clients that shoud not be affected. + clients that should not be affected. </para></listitem> <listitem><para> Finally, <command>bcfg2-repo-validate</command> should be @@ -472,9 +477,10 @@ <para> The goal for this example is to configure NTP for an entire - network. This means several things. All clients should run NTP - as clients. One client should run NTP as a server, and - ntp clients should use it instead of an external server. + network. This implies several things. All clients should run + NTP as clients. Some hosts should run NTP as a server, and + other hosts should use local NTP service instead of an + external server. </para> <orderedlist> |