From 391406c85d86dc931f3fdb2483a14d0f1e7e6355 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Tue, 9 Nov 2010 00:15:43 +0100 Subject: doc: Massive update --- doc/architecture/client.txt | 112 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 doc/architecture/client.txt (limited to 'doc/architecture/client.txt') diff --git a/doc/architecture/client.txt b/doc/architecture/client.txt new file mode 100644 index 000000000..77da25621 --- /dev/null +++ b/doc/architecture/client.txt @@ -0,0 +1,112 @@ +.. -*- mode: rst -*- + +.. _architecture-client: + +The Bcfg2 Client +================ + +The Bcfg2 client performs all client configuration or reconfiguration +operations. It renders a declarative configuration specification, provided +by the Bcfg2 server, into a set of configuration operations which will, +if executed, attempt to change the client's state into that described by +the configuration specification. Conceptually, the Bcfg2 client serves to +isolate the Bcfg2 server and specification from the imperative operations +required to implement configuration changes. + +This isolation allows declarative specifications to be manipulated +symbolically on the server, without needing to understand the properties +of the underlying system tools. In this way, the Bcfg2 client acts +as a sort of expert system that *knows* how to implement declarative +configuration changes. + +The operation of the Bcfg2 client is intended to be as simple as +possible. The normal configuration process consists of four main steps: + +* **Probe Execution** + + 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. + +* **Configuration Download and Inventory** + + 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. 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 are executed 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 if the client has + any extra configuration that isn't present. This provides a fairly + rigorous notion of client configuration congruence. 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. + +* **Configuration Update** + + 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. 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-dependent. 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. + +* **Statistics Upload** + + 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): + + * Overall client status (clean/dirty) + * List of modified configuration entries + * List of uncorrectable configuration entries + * List of unmanaged configuration entries + +Architecture Abstraction +------------------------ + +The Bcfg2 client internally supports the administrative tools available +on different architectures. For example, ``rpm`` and ``apt-get`` are +both supported, allowing operation of Debian, Redhat, SUSE, and Mandriva +systems. The client toolset is determined based on the availability of +client tools. The client includes a series of libraries which describe +how to interact with the system tools on a particular platform. + +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, symlinks, hardlinks, etc., are +included here. Two other libraries subclass this one, providing support +for Debian and rpm-based systems. + +The Debian toolset includes support for apt-get and update-rc.d. These +tools provide the ability to install and remove packages, and to install +and remove services. + +The Redhat toolset includes support for rpm and chkconfig. Any other +platform that uses these tools can also use this toolset. Hence, all +of the other familiar rpm-based distributions can use this toolset +without issue. + +Other platforms can easily use the POSIX toolset, ignoring support for +packages or services. Alternatively, adding support for new toolsets +isn't difficult. Each toolset consists of about 125 lines of python code. -- cgit v1.2.3-1-g7c22