diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/server/plugins/generators/account.txt | 12 | ||||
| -rw-r--r-- | doc/server/plugins/generators/cfg.txt | 80 | ||||
| -rw-r--r-- | doc/server/plugins/generators/decisions.txt | 40 | ||||
| -rw-r--r-- | doc/server/plugins/generators/hostbase.txt | 4 | ||||
| -rw-r--r-- | doc/server/plugins/generators/nagiosgen.txt | 15 | ||||
| -rw-r--r-- | doc/server/plugins/generators/packages.txt | 149 | ||||
| -rw-r--r-- | doc/server/plugins/generators/pkgmgr.txt | 89 | ||||
| -rw-r--r-- | doc/server/plugins/generators/tcheetah.txt | 20 | ||||
| -rw-r--r-- | doc/server/plugins/grouping/metadata.txt | 29 | ||||
| -rw-r--r-- | doc/server/plugins/index.txt | 26 | ||||
| -rw-r--r-- | doc/server/plugins/version/bzr.txt | 11 | ||||
| -rw-r--r-- | doc/server/plugins/version/fossil.txt | 6 | ||||
| -rw-r--r-- | doc/server/plugins/version/git.txt | 11 | ||||
| -rw-r--r-- | doc/server/plugins/version/svn.txt | 8 | ||||
| -rw-r--r-- | doc/server/reports/index.txt | 8 | ||||
| -rw-r--r-- | doc/server/reports/static.txt | 74 | ||||
| -rw-r--r-- | doc/unsorted/contribute.txt | 35 |
17 files changed, 464 insertions, 153 deletions
diff --git a/doc/server/plugins/generators/account.txt b/doc/server/plugins/generators/account.txt index 93b3b8b88..3bae157cc 100644 --- a/doc/server/plugins/generators/account.txt +++ b/doc/server/plugins/generators/account.txt @@ -20,7 +20,11 @@ User access data is stored in three files in the Account directory: * rootlist (a list of user:host pairs for scoped root privs) * useraccess (a list of user:host pairs for login access) -SSH keys are stored in files named $username.key; these are installed into root's authorized keys for users in the superusers list as well as for the pertitent users in the rootlike file (for the current system). - -Authentication data is read in from (static|dyn).(passwd|group) The static ones are for system local ones, while the dyn. versions are for external synchronization (from ldap/nis/etc) -There is also a static.limits.conf that provides the limits.conf header and any static entries. +SSH keys are stored in files named $username.key; these are installed +into root's authorized keys for users in the superusers list as well as +for the pertitent users in the rootlike file (for the current system). + +Authentication data is read in from (static|dyn).(passwd|group) The static +ones are for system local ones, while the dyn. versions are for external +synchronization (from ldap/nis/etc). There is also a static.limits.conf +that provides the limits.conf header and any static entries. diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt index 28752187d..5e8c43427 100644 --- a/doc/server/plugins/generators/cfg.txt +++ b/doc/server/plugins/generators/cfg.txt @@ -6,57 +6,100 @@ Cfg === -The Cfg plugin provides a repository to describe configuration file contents for clients. In its simplest form, the Cfg repository is just a directory tree modeled off of the directory tree on your client machines. +The Cfg plugin provides a repository to describe configuration file +contents for clients. In its simplest form, the Cfg repository is just a +directory tree modeled off of the directory tree on your client machines. The Cfg Repository ================== -The Cfg plugin is enabled by including `Cfg` on the `plugins` line of the `[server]` section of your Bcfg2 server config file. The repository itself lives in `/var/lib/bcfg2/Cfg`, assuming you are using the default repository location of `/var/lib/bcfg2`. The contents of this directory are a series of directories corresponding to the real-life locations of the files on your clients, starting at the root level. For example:: +The Cfg plugin is enabled by including `Cfg` on the `plugins` line of +the `[server]` section of your Bcfg2 server config file. The repository +itself lives in `/var/lib/bcfg2/Cfg`, assuming you are using the default +repository location of `/var/lib/bcfg2`. The contents of this directory +are a series of directories corresponding to the real-life locations of +the files on your clients, starting at the root level. For example:: lueningh@tg-prez:~/bcfg2/repository> ls Cfg bin/ boot/ etc/ opt/ root/ usr/ var/ -Specific config files go in like-named directories in this heirarchy. For example the password file, `/etc/passwd`, goes in `Cfg/etc/passwd/passwd`, while the ssh pam module config file, `/etc/pam.d/sshd`, goes in `Cfg/etc/pam.d/sshd/sshd`. The reason for the like-name directory is to allow multiple versions of each file to exist, as described below. Note that these files are exact copies of what will appear on the client machine - no templates, XML wrappers, etc. +Specific config files go in like-named directories in this +heirarchy. For example the password file, `/etc/passwd`, goes +in `Cfg/etc/passwd/passwd`, while the ssh pam module config file, +`/etc/pam.d/sshd`, goes in `Cfg/etc/pam.d/sshd/sshd`. The reason for the +like-name directory is to allow multiple versions of each file to exist, +as described below. Note that these files are exact copies of what will +appear on the client machine - no templates, XML wrappers, etc. Group-Specific Files ==================== -It is often that you want one version of a config file for all of your machines except those in a particular group. For example, `/etc/fstab` should look alike on all of your desktop machines, but should be different on your file servers. Bcfg can handle this case through use of group-specific files. +It is often that you want one version of a config file for all of your +machines except those in a particular group. For example, `/etc/fstab` +should look alike on all of your desktop machines, but should be +different on your file servers. Bcfg2 can handle this case through use +of group-specific files. -As mentioned above, all Cfg entries live in like-named directories at the end of their directory tree. In the case of `fstab`, the file at `Cfg/etc/fstab/fstab` will be handed out by default to any client that asks for a copy of `/etc/fstab`. Group-specific files are located in the same directory and are named with the syntax:: +As mentioned above, all Cfg entries live in like-named directories at +the end of their directory tree. In the case of `fstab`, the file at +`Cfg/etc/fstab/fstab` will be handed out by default to any client that +asks for a copy of `/etc/fstab`. Group-specific files are located in +the same directory and are named with the syntax:: /path/to/filename/filename.GNN_groupname -in which ''NN'' is a priority number where '00' is lowest and '99' is highest, and ''groupname'' is the name of a group defined in `Metadata/groups.xml`. Back to our `fstab` example, we might have a `Cfg/etc/fstab/` directory that looks like:: +in which ''NN'' is a priority number where '00' is lowest and '99' +is highest, and ''groupname'' is the name of a group defined in +`Metadata/groups.xml`. Back to our `fstab` example, we might have a +`Cfg/etc/fstab/` directory that looks like:: fstab fstab.G50_server fstab.G99_fileserver -By default, clients will receive the plain `fstab` file when they request `/etc/fstab`. Any machine that is in the `server` group, however, will instead receive the `fstab.G50_server` file. Finally, any machine that is in the `fileserver` group will receive the `fstab.G99_fileserver` file, even if they are also in the `server` group. +By default, clients will receive the plain `fstab` file when they request +`/etc/fstab`. Any machine that is in the `server` group, however, will +instead receive the `fstab.G50_server` file. Finally, any machine that +is in the `fileserver` group will receive the `fstab.G99_fileserver` +file, even if they are also in the `server` group. Host-Specific Files =================== -Similar to the case with group-specific files, there are cases where a specific machine should have a different version of a file than all others. This can be accomplished with host-specific files. The format of a host-specific file name is:: +Similar to the case with group-specific files, there are cases where +a specific machine should have a different version of a file than all +others. This can be accomplished with host-specific files. The format +of a host-specific file name is:: /path/to/filename/filename.H_host.example.com -Host-specific files have a higher priority than group specific files. Again, the `fstab` example:: +Host-specific files have a higher priority than group specific +files. Again, the `fstab` example:: fstab fstab.G50_server fstab.G99_fileserver fstab.H_host.example.com -In this case, `host.example.com` will always get the host-specific version, even if it is part of the `server` or `fileserver` (or both) classes. +In this case, `host.example.com` will always get the host-specific +version, even if it is part of the `server` or `fileserver` (or both) +classes. -.. note:: If you have the ability to choose between using a group-specific file and a host-specific file, it is almost always best to use a group-specific one. That way if a hostname changes or an extra copy of a particular client is built, it will get the same changes as the original. +.. note:: + + If you have the ability to choose between using a group-specific and + a host-specific file, it is almost always best to use a group-specific + one. That way if a hostname changes or an extra copy of a particular + client is built, it will get the same changes as the original. Info files ========== -By default, Cfg writes files to the filesystem with owner `root`, group `root`, and mode 644 (read and write for owner, read only for group and other). These options, and a few others, can be overridden through use of `:info` files. Each config file directory can have a `:info` file if needed. The possible fields in a `:info` file are: +By default, Cfg writes files to the filesystem with owner `root`, group +`root`, and mode 644 (read and write for owner, read only for group +and other). These options, and a few others, can be overridden through +use of `:info` files. Each config file directory can have a `:info` +file if needed. The possible fields in a `:info` file are: +-----------+-------------------+------------------------------------------------------+---------+ | Field | Possible values | Description | Default | @@ -78,7 +121,8 @@ A sample `:info` file for CGI script on a web server might look like:: group: www perms: 0755 -Back to the `fstab` example again, our final `Cfg/etc/fstab/` directory might look like:: +Back to the `fstab` example again, our final `Cfg/etc/fstab/` directory +might look like:: :info fstab @@ -89,11 +133,13 @@ Back to the `fstab` example again, our final `Cfg/etc/fstab/` directory might lo info.xml files ============== -This feature is included in version 0.9.5pre3 and newer of the bcfg2 server. - -info.xml files add the ability to specify different sets of file metadata on a group by group basis. These files are XML, and work similarly to those used by [wiki:Plugins/Rules Rules] or [wiki:Plugins/Pkgmgr Pkgmgr]. +info.xml files add the ability to specify different sets of file metadata +on a group by group basis. These files are XML, and work similarly +to those used by :ref:`Rules <server-plugins-generators-rules>` or +:ref:`Pkgmgr <server-plugins-generators-pkgmgr>`. -The following specifies a different global set of permissions (root/sys/0651) than on clients in group webserver (root/root/0652) +The following specifies a different global set of permissions +(root/sys/0651) than on clients in group webserver (root/root/0652) .. code-block:: xml diff --git a/doc/server/plugins/generators/decisions.txt b/doc/server/plugins/generators/decisions.txt index 9d33a9b31..52e5c316e 100644 --- a/doc/server/plugins/generators/decisions.txt +++ b/doc/server/plugins/generators/decisions.txt @@ -6,11 +6,27 @@ Decisions ========= -This page describes the Decisions plugin. The client has support for a centralized set of per-entry installation decisions. This approach is needed when particular changes are deemed "high risk"; this gives the ability to centrally specify these changes, but only install them on clients when administrator supervision is available. Because collaborative configuration is one of the remaining hard issues in configuration management, these issues typically crop up in environments with several administrators and much configuration variety. - -In these cases, the client can be configured to run in either a whitelist or blacklist mode, wherein a list of entries is downloaded from the server. The client uses this list to determine which incorrect entries should be corrected during the current run of the installation tool. The Decision plugin is the only stock plugin that generates entries for client's whitelists or blacklists. - -The Decision plugin uses a directory in the bcfg2 repository called Decisions. Files in the Decisions subdirectory are named similarly to files managed by Cfg, probes, TCheetah, and TGenshi. File basenames are either whitelist or blacklist. These files have a simple format; the following is an example. +This page describes the Decisions plugin. The client has support for a +centralized set of per-entry installation decisions. This approach is +needed when particular changes are deemed "high risk"; this gives the +ability to centrally specify these changes, but only install them on +clients when administrator supervision is available. Because collaborative +configuration is one of the remaining hard issues in configuration +management, these issues typically crop up in environments with several +administrators and much configuration variety. + +In these cases, the client can be configured to run in either a whitelist +or blacklist mode, wherein a list of entries is downloaded from the +server. The client uses this list to determine which incorrect entries +should be corrected during the current run of the installation tool. The +Decision plugin is the only stock plugin that generates entries for +client's whitelists or blacklists. + +The Decision plugin uses a directory in the bcfg2 repository called +Decisions. Files in the Decisions subdirectory are named similarly to +files managed by Cfg, probes, TCheetah, and TGenshi. File basenames +are either whitelist or blacklist. These files have a simple format; +the following is an example. .. code-block:: xml @@ -26,6 +42,14 @@ The Decision plugin uses a directory in the bcfg2 repository called Decisions. F vim: ft=xml --> -This example, included as a whitelist due to its name, enables all services, and the path entry named /etc/apt/apt.conf to be installed on systems running in whitelist mode; all other entry installation will be surpressed. - -When a client askes for its whitelist or blacklist, all of the files pertaining to that client of the correct type are aggregated into a single list. This list is sent to the client. Note that this list is only generated when a client is run with the appropriate option (-l (whitelist|blacklist)); client behavior is not controlled unless this option is used. +This example, included as a whitelist due to its name, enables all +services, and the path entry named ``/etc/apt/apt.conf`` to be installed +on systems running in whitelist mode; all other entry installation will +be surpressed. + +When a client askes for its whitelist or blacklist, all of the files +pertaining to that client of the correct type are aggregated into a +single list. This list is sent to the client. Note that this list is +only generated when a client is run with the appropriate option (-l +(whitelist|blacklist)); client behavior is not controlled unless this +option is used. diff --git a/doc/server/plugins/generators/hostbase.txt b/doc/server/plugins/generators/hostbase.txt index 6ba92a4e1..13e2ecabb 100644 --- a/doc/server/plugins/generators/hostbase.txt +++ b/doc/server/plugins/generators/hostbase.txt @@ -66,7 +66,9 @@ you can explore the web interface. Try adding a host and a zone. You'll see that a ".rev" zone already exists. This is where information for reverse files will go. -For production, you'll want to have this configured for Apache with mod_python. Here is an example of how to configure Hostbase as a virtual host. +For production, you'll want to have this configured for Apache with +mod_python. Here is an example of how to configure Hostbase as a +virtual host. .. code-block:: html diff --git a/doc/server/plugins/generators/nagiosgen.txt b/doc/server/plugins/generators/nagiosgen.txt index 0815aab99..f6362dbdd 100644 --- a/doc/server/plugins/generators/nagiosgen.txt +++ b/doc/server/plugins/generators/nagiosgen.txt @@ -6,11 +6,11 @@ NagiosGen ========= -This page describes the installation and use of the `NagiosGen -<http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/src/lib/Server/Plugins/NagiosGen.py>`_ -plugin. +This page describes the installation and use of the `NagiosGen`_ plugin. -Update /etc/bcfg2.conf, adding NagiosGen to plugins:: +.. _NagiosGen: http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/src/lib/Server/Plugins/NagiosGen.py + +Update ``/etc/bcfg2.conf``, adding NagiosGen to plugins:: plugins = SSHbase,Cfg,Pkgmgr,Rules,TCheetah,TWbase,NagiosGen @@ -149,7 +149,7 @@ Create a nagios bcfg2 bundle /var/lib/bcfg2/Bundler/nagios.xml </Bundle> Assign clients to nagios groups in -/var/lib/bcfg2/Metadata/groups.xml +``/var/lib/bcfg2/Metadata/groups.xml`` .. code-block:: xml @@ -165,4 +165,7 @@ Update nagios configuration file to use nagiosgen.cfg:: cfg_file=/etc/nagios/nagiosgen.cfg -Note that some of these files are built on demand, each time a client in group "nagios-server" checks in with the bcfg2 server. Local nagios instances can be configured to use the !NagiosGen directory in the bcfg2 repository directly. +Note that some of these files are built on demand, each time a client +in group "nagios-server" checks in with the bcfg2 server. Local nagios +instances can be configured to use the !NagiosGen directory in the bcfg2 +repository directly. diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt index df221d897..1b12e88fd 100644 --- a/doc/server/plugins/generators/packages.txt +++ b/doc/server/plugins/generators/packages.txt @@ -6,12 +6,25 @@ Packages ======== -This page documents the Packages plugin. Packages is an alternative to [wiki:Plugins/Pkgmgr Pkgmgr] for specifying package entries for clients. Where Pkgmgr explicitly specifies package entry information, Packages delegates control of package version information to the underlying package manager, installing the latest version available through those channels. +This page documents the Packages plugin. Packages is an alternative to +:ref:`Pkgmgr <server-plugins-generators-pkgmgr>` for specifying package +entries for clients. Where Pkgmgr explicitly specifies package entry +information, Packages delegates control of package version information to +the underlying package manager, installing the latest version available +through those channels. "Magic Groups" ============== -Packages is the only plugin that uses "magic groups". Most plugins operate based on client group memberships, without any concern for the particular names chosen for groups by the user. The Packages plugin is the sole exception to this rule. Packages needs to "know" two different sorts of facts about clients. The first is the basic OS/distro of the client, enabling classes of sources. The second is the architecture of the client, enabling sources for a given architecture. In addition to these magic groups, each source may also specify a non-magic group to limit the source's applicability to group member clients. +Packages is the only plugin that uses "magic groups". Most plugins +operate based on client group memberships, without any concern for the +particular names chosen for groups by the user. The Packages plugin is +the sole exception to this rule. Packages needs to "know" two different +sorts of facts about clients. The first is the basic OS/distro of the +client, enabling classes of sources. The second is the architecture of +the client, enabling sources for a given architecture. In addition to +these magic groups, each source may also specify a non-magic group to +limit the source's applicability to group member clients. +-----------+----------+--------------+ | Source | OS Group | Architecture | @@ -30,29 +43,51 @@ Packages is the only plugin that uses "magic groups". Most plugins operate based Limiting sources to groups ========================== -Each source can also specify explicit group memberships. In the following example, the ubuntu-hardy group is also required. Finally, clients must be a member of the appropriate architecture group, in this case, either i386 or amd64. In total, in order for this source to be associated with a client is for the client to be in one of the sentinel groups (debian, ubuntu, or nexenta), the explicit group ubuntu-hardy, and any of the architecture groups (i386 or amd64). +Each source can also specify explicit group memberships. In the following +example, the ubuntu-hardy group is also required. Finally, clients must +be a member of the appropriate architecture group, in this case, either +i386 or amd64. In total, in order for this source to be associated with +a client is for the client to be in one of the sentinel groups (debian, +ubuntu, or nexenta), the explicit group ubuntu-hardy, and any of the +architecture groups (i386 or amd64). -Memberships in architecture groups is needed so that Packages can map software sources to clients. There is no other way to handle this than to impose +Memberships in architecture groups is needed so that Packages can map +software sources to clients. There is no other way to handle this than +to impose -When multiple sources are specified, clients are associated with each source to which they apply (based on group memberships, as described above). Packages and dependencies are resolved from all applicable sources. +When multiple sources are specified, clients are associated with each +source to which they apply (based on group memberships, as described +above). Packages and dependencies are resolved from all applicable +sources. Setup ===== + Three basic steps are required for Packages to work properly. - 1. Create Packages/config.xml. This file should look approximately like the example below, and describes both which software repositories should be used, and which clients are eligible to use each one. - 2. Ensure that clients are members of the proper groups. Each client should be a member of one of the sentinel groups listed above (debian/ubuntu/redhat/centos/nexenta), all of the groups listed in the source (like ubuntu-intrepid or centos-5.2 in the following examples), and one of the architecture groups listed in the source configuration (i386, amd64 or x86_64 in the following examples). '''Failure to do this will result in the source either not applying to the client, or only architecture independent packages being made available to the client.''' - 3. Add Package entries to bundles. - 4. Sit back and relax, as dependencies are resolved, and automatically added to client configurations. + +#. Create Packages/config.xml. This file should look approximately like the example below, and describes both which software repositories should be used, and which clients are eligible to use each one. +#. Ensure that clients are members of the proper groups. Each client should be a member of one of the sentinel groups listed above (debian/ubuntu/redhat/centos/nexenta), all of the groups listed in the source (like ubuntu-intrepid or centos-5.2 in the following examples), and one of the architecture groups listed in the source configuration (i386, amd64 or x86_64 in the following examples). '''Failure to do this will result in the source either not applying to the client, or only architecture independent packages being made available to the client.''' +#. Add Package entries to bundles. +#. Sit back and relax, as dependencies are resolved, and automatically added to client configurations. Prerequisite Resolution ======================= -Packages provides a prerequisite resolution mechanism which has no analogue in Pkgmgr. During configuration generation, all structures are processed. After this phase, but before entry binding, a list of packages and the client metadata instance is passed into Packages' resolver. This process determines a superset of packages that will fully satisfy dependencies of all package entries included in structures, and reports any prerequisites that cannot be satisfied. This facility should largely remove the need to use the [wiki:Plugins/Base Base] plugin. +Packages provides a prerequisite resolution mechanism which has no +analogue in Pkgmgr. During configuration generation, all structures are +processed. After this phase, but before entry binding, a list of packages +and the client metadata instance is passed into Packages' resolver. This +process determines a superset of packages that will fully satisfy +dependencies of all package entries included in structures, and reports +any prerequisites that cannot be satisfied. This facility should largely +remove the need to use the :ref:`Base <server-plugins-structures-base>` +plugin. Example usage ============= -Create a config.xml file in the Packages directory that looks something like this: +Create a config.xml file in the Packages directory that looks something +like this: .. code-block:: xml @@ -113,12 +148,15 @@ Yum sources can be similarly specified: Configuration Updates ===================== -Packages will reload its configuration upon an explicit command via bcfg2-admin.:: +Packages will reload its configuration upon an explicit command via +bcfg2-admin.:: [0:3711] bcfg2-admin xcmd Packages.Refresh True -During this command (which will take some time depending on the quantity and size of the sources listed in the configuration file), the server will report information like:: +During this command (which will take some time depending on the quantity +and size of the sources listed in the configuration file), the server +will report information like:: Packages: Updating http://mirror.anl.gov/ubuntu//dists/jaunty/main/binary-i386/Packages.gz Packages: Updating http://mirror.anl.gov/ubuntu//dists/jaunty/main/binary-amd64/Packages.gz @@ -128,27 +166,35 @@ During this command (which will take some time depending on the quantity and siz Packages: Updating http://mirror.centos.org/centos/5/extras/x86_64/repodata/filelists.xml.gz Packages: Updating http://mirror.centos.org/centos/5/extras/x86_64/repodata/primary.xml.gz -Once line per file download needed. Packages/config.xml will be reloaded at this time, so any source specification changes (new or modified sources in this file) will be reflected by the server at this point. +Once line per file download needed. Packages/config.xml will be reloaded +at this time, so any source specification changes (new or modified +sources in this file) will be reflected by the server at this point. Availability ============ -Packages was added in 1.0pre1, with APT support. YUM support was added for 1.0pre2. Support for other package managers (Portage, Zypper, IPS, etc) remain to be added. +Packages was added in 1.0pre1, with APT support. YUM support was added +for 1.0pre2. Support for other package managers (Portage, Zypper, IPS, +etc) remain to be added. Validation ========== -A schema for Packages/config.xml is included; config.xml can be validated using bcfg2-repo-validate. Note that the schema requires that elements be specified in the above order. +A schema for Packages/config.xml is included; config.xml can be validated +using bcfg2-repo-validate. Note that the schema requires that elements +be specified in the above order. Limitations =========== -Packages does not do traditional caching as other plugins do. Changes to the Packages config file require a server restart for the time being. +Packages does not do traditional caching as other plugins do. Changes +to the Packages config file require a server restart for the time being. Package Verification ==================== -In order to do disable per-package verification Pkgmgr style, you will need to use [wiki:BoundEntry BoundEntries] like below +In order to do disable per-package verification Pkgmgr style, you will +need to use :ref:`BoundEntries <unsorted-boundentry>` like below .. code-block:: xml @@ -190,9 +236,16 @@ The dependency resolver used in Packages can be run in debug mode:: Package libgcc1: adding new deps ['gcc-4.3-base'] (set(['debconf', 'libgcc1', 'lsb-base', 'libtext-wrapi18n-perl', 'libtext-iconv-perl', 'sed', 'passwd', 'findutils', 'libpam0g', 'openssh-client', 'debconf-i18n', 'libselinux1', 'zlib1g', 'adduser', 'libwrap0', 'ncurses-bin', 'libssl0.9.8', 'liblocale-gettext-perl', 'libkeyutils1', 'libpam-runtime', 'libpam-modules', 'openssh-server', 'libkrb53', 'ssh', 'libncurses5', 'libc6', 'libedit2', 'libcomerr2', 'dpkg', 'perl-base', 'libdb4.7', 'libtext-charwidth-perl', 'gcc-4.3-base', 'debianutils']), set([]), 'deb') -This will show why the resolver is acting as it is. Replace "ubik3" and ['ssh'] with a client name and list of packages, respectively. Also, a more polished interface to this functionality is coming as well. +This will show why the resolver is acting as it is. Replace "ubik3" and +['ssh'] with a client name and list of packages, respectively. Also, +a more polished interface to this functionality is coming as well. -Each line starting with Package: <name> describes a set of new prerequisites pulled in by a package. Lines starting with VPackage <vname> describe provides entries and their mappings to required names. The last line describes the overall results of the resolver, with three fields: a list of packages that should be installed, a list of unresolved requirements, and a type for these packages. +Each line starting with Package: <name> describes a set of new +prerequisites pulled in by a package. Lines starting with VPackage <vname> +describe provides entries and their mappings to required names. The last +line describes the overall results of the resolver, with three fields: +a list of packages that should be installed, a list of unresolved +requirements, and a type for these packages. Using bcfg2-server ------------------ @@ -204,23 +257,55 @@ Once the server is started, enable debugging via bcfg2-admin:: TODO list ========= - * Zypper support - * Portage support - * Explicit version pinning (a la Pkgmgr) +* Zypper support +* Portage support +* Explicit version pinning (a la Pkgmgr) Developing for Packages ======================= -In order to support a given client package tool driver, that driver must support use of the auto value for the version attribute in Package entries. In this case, the tool driver views the current state of available packages, and uses the underlying package manager's choice of correct package version in lieu of an explicit, centrally-specified, version. This support enables Packages to provide a list of Package entries with version='auto'. Currently, the APT and YUMng drivers support this feature. Note that package management systems without any network support cannot operate in this fashion, so RPMng and SYSV will never be able to use Packages. Emerge, Zypper, IPS, and Blastwave all have the needed features to be supported by Packages, but support has not yet been written. - -Packages fills two major functions in configuration generation. The first is to provide entry level binding support for Package entries included in client configurations. This function is quite easy to implement; Packages determines (based on client group membership) if the package is available for the client system, and which type it has. Because version='auto' is used, no version determination needs to be done. - -The second major function is more complex. Packages ensures that client configurations include all package-level prerequisites for package entries explicitly included in the configuration. In order to support this, Packages needs to directly process network data for package management systems (the network sources for apt or yum, for examples), process these files, and build data structures describing prerequisites and the providers of those functions/paths. To simplify implementations of this, there is a generic base class (Bcfg2.Server.Plugins.Packages.Source) that provides a framework for fetching network data via HTTP, processing those sources (with subclass defined methods for processing the specific format provided by the tool), a generic dependency resolution method, and a caching mechanism that greatly speeds up server/bcfg2-info startup. +In order to support a given client package tool driver, that driver +must support use of the auto value for the version attribute in Package +entries. In this case, the tool driver views the current state of +available packages, and uses the underlying package manager's choice of +correct package version in lieu of an explicit, centrally-specified, +version. This support enables Packages to provide a list of Package +entries with version='auto'. Currently, the APT and YUMng drivers support +this feature. Note that package management systems without any network +support cannot operate in this fashion, so RPMng and SYSV will never be +able to use Packages. Emerge, Zypper, IPS, and Blastwave all have the +needed features to be supported by Packages, but support has not yet +been written. + +Packages fills two major functions in configuration generation. The first +is to provide entry level binding support for Package entries included +in client configurations. This function is quite easy to implement; +Packages determines (based on client group membership) if the package +is available for the client system, and which type it has. Because +version='auto' is used, no version determination needs to be done. + +The second major function is more complex. Packages ensures that client +configurations include all package-level prerequisites for package entries +explicitly included in the configuration. In order to support this, +Packages needs to directly process network data for package management +systems (the network sources for apt or yum, for examples), process +these files, and build data structures describing prerequisites and the +providers of those functions/paths. To simplify implementations of this, +there is a generic base class (Bcfg2.Server.Plugins.Packages.Source) +that provides a framework for fetching network data via HTTP, processing +those sources (with subclass defined methods for processing the specific +format provided by the tool), a generic dependency resolution method, +and a caching mechanism that greatly speeds up server/bcfg2-info startup. Each source type must define: - * a get_urls attribute (and associated urls property) that describes the URLS where to get data from. - * a read_files method that reads and processes the downloaded files -Sources may define a get_provides method, if provides are complex. For example, provides in rpm can be either rpm names or file paths, so multiple data sources need to be multiplexed. +* a get_urls attribute (and associated urls property) that describes + the URLS where to get data from. +* a read_files method that reads and processes the downloaded files + +Sources may define a get_provides method, if provides are complex. For +example, provides in rpm can be either rpm names or file paths, so +multiple data sources need to be multiplexed. -The APT source in src/lib/Server/Plugins/Packages.py provides a relatively simple implementation of a source. +The APT source in ``src/lib/Server/Plugins/Packages.py`` provides a +relatively simple implementation of a source. diff --git a/doc/server/plugins/generators/pkgmgr.txt b/doc/server/plugins/generators/pkgmgr.txt index 81ff6b8a3..a9c166446 100644 --- a/doc/server/plugins/generators/pkgmgr.txt +++ b/doc/server/plugins/generators/pkgmgr.txt @@ -14,16 +14,26 @@ Pkgmgr old way is "multiarch". '''This document needs to be updated and include version of Bcfg2 where change took place.''' -The Pkgmgr plugin resolves the Abstract Configuration Entity "Package" to a package specification that the client can use to detect, verify and install the specified package. +The Pkgmgr plugin resolves the Abstract Configuration Entity "Package" +to a package specification that the client can use to detect, verify +and install the specified package. -For a package specification to be included in the Literal configuration the name attribute from an Abstract Package Tag (from Base or Bundler) must match the name attribute of a Package tag in Pkgmgr, along with the appropriate group associations of course. +For a package specification to be included in the Literal configuration +the name attribute from an Abstract Package Tag (from Base or Bundler) +must match the name attribute of a Package tag in Pkgmgr, along with +the appropriate group associations of course. -Each file in the Pkgmgr directory has a priority. This allows the same package to be served by multiple files. The priorities can be used to break ties in the case that multiple files serve data for the same package. +Each file in the Pkgmgr directory has a priority. This allows the +same package to be served by multiple files. The priorities can be +used to break ties in the case that multiple files serve data for the +same package. Usage of Groups in Pkgmgr ========================= -Groups are used by the Pkgmgr plugin, along with host metadata, for selecting the package entries to include in the clients literal configuration. They can be thought of as:: +Groups are used by the Pkgmgr plugin, along with host metadata, +for selecting the package entries to include in the clients literal +configuration. They can be thought of as:: if client is a member of group1 then assign to literal config @@ -116,7 +126,9 @@ The Package Tag may have the following attributes: Client Tag ---------- -The Client Tag is used in a PackageList for selecting the package entries to include in the clients literal configuration. Its function is similar to the Group tag in this context. It can be thought of as:: +The Client Tag is used in a PackageList for selecting the package entries +to include in the clients literal configuration. Its function is similar +to the Group tag in this context. It can be thought of as:: if client is name then assign to literal config @@ -134,13 +146,20 @@ The Client Tag may have the following attributes: Pkgmgr Directory ================ -The Pkgmgr/ directory keeps the XML files that define what packages are available for a host or image and where to find those packages. All the files in the directory are processed. +The Pkgmgr/ directory keeps the XML files that define what packages +are available for a host or image and where to find those packages. +All the files in the directory are processed. -The names of the XML files have no special meaning to Bcfg2; they are simply named so it's easy for the administrator to know what the contents hold. All Packages could be kept in a single file if so desired. Bcfg2 simply uses the Groups in the files and priorities to determine how to assign Packages to a host's literal configuration. +The names of the XML files have no special meaning to Bcfg2; they +are simply named so it's easy for the administrator to know what the +contents hold. All Packages could be kept in a single file if so desired. +Bcfg2 simply uses the Groups in the files and priorities to determine +how to assign Packages to a host's literal configuration. Listed detailed below is one possible structure for the Pkgmgr directory. -The files are structured to contain particular portions of distribution repositories. +The files are structured to contain particular portions of distribution +repositories. The files in the directory are:: @@ -164,7 +183,8 @@ The files in the directory are:: rhel-ws-4-x86-updates.xml rhel-ws-4-x86.xml -As can be seen the file names have been selected to indicate what the contents are and have been split by Vendor, product and repository area. +As can be seen the file names have been selected to indicate what the +contents are and have been split by Vendor, product and repository area. A partial listing of the centos-4-x86_64.xml is below @@ -208,13 +228,26 @@ A partial listing of the centos-4-x86_64.xml is below </Group> </PackageList> -Here it can be seen that the data is encapsulated in a !PackageList Tag which describes the URI of the files described, the type of package, and the priority of the files in this list. +Here it can be seen that the data is encapsulated in a !PackageList Tag +which describes the URI of the files described, the type of package, +and the priority of the files in this list. -The priority is used to decide which specific file to use when there are multiple files that could be used for a particular host. The highest priority file is the one that is used. +The priority is used to decide which specific file to use when there are +multiple files that could be used for a particular host. The highest +priority file is the one that is used. -Using this system, it is possible to have a file that contains all the Packages from the original installation, centos-4-x86_64.xml in this case, and then create a new file that contains updates that are made available afterwards, centos-4-x86_64-updates.xml and centos-4-noarch-updates.xml in this case. The priority of the update PackageLists just needs to be higher so that they will be selected instead of the original installation Packages. +Using this system, it is possible to have a file that contains all the +Packages from the original installation, centos-4-x86_64.xml in this case, +and then create a new file that contains updates that are made available +afterwards, centos-4-x86_64-updates.xml and centos-4-noarch-updates.xml +in this case. The priority of the update PackageLists just needs to be +higher so that they will be selected instead of the original installation +Packages. -The backup.example.com.xml contains a packalist for a specific host which is qualified by the Client tag. Its Packages have a higher priority than the update Packages. This is because this particular host requires special Packages that are older than the ones available in the updates. +The backup.example.com.xml contains a packalist for a specific host which +is qualified by the Client tag. Its Packages have a higher priority +than the update Packages. This is because this particular host requires +special Packages that are older than the ones available in the updates. .. code-block:: xml @@ -233,13 +266,20 @@ The backup.example.com.xml contains a packalist for a specific host which is qua </Client> </PackageList> -Simplifying Multi-Architecture Environments with [wiki:altsrc Altsrc] -===================================================================== +Simplifying Multi-Architecture Environments with :ref:`Altsrc <unsorted-altsrc>` +================================================================================ -This feature is available in 0.9.5pre3 or newer versions of the bcfg2 server. +Frequently multi-architecture environments (typically x86_64) will run +into problems needing to specify different architectures on different +groups for clients. For example, desktop machines may install 32-bit +compatibility packages in addition to 64-bit ones, while servers +may install only 64-bit packages. Specifying this in the Pkgmgr was +onerous, because different package targets (64bit, 32+64, etc) needed +to be specified on a package by group basis. Two features have been +implemented that should ease this situation considerably. -Frequently multi-architecture environments (typically x86_64) will run into problems needing to specify different architectures on different groups for clients. For example, desktop machines may install 32-bit compatibility packages in addition to 64-bit ones, while servers may install only 64-bit packages. Specifying this in the Pkgmgr was onerous, because different package targets (64bit, 32+64, etc) needed to be specified on a package by group basis. Two features have been implemented that should ease this situation considerably. -* the [wiki:altsrc] feature adds the ability to add a "bind as" directive to entries. For example, the following entry, in a bundle: +* The :ref:`Altsrc <unsorted-altsrc>` feature adds the ability to add a "bind as" directive + to entries. For example, the following entry, in a bundle: .. code-block:: xml @@ -247,7 +287,8 @@ Frequently multi-architecture environments (typically x86_64) will run into prob would bind as if it were named bar, while the entry would still appear named "foo" in the client configuration specification. -* Pkgmgr now builds virtual package targets for any package with Instance client elements. This means that if a client attempts to bind: +* Pkgmgr now builds virtual package targets for any package with Instance + client elements. This means that if a client attempts to bind: .. code-block:: xml @@ -279,10 +320,14 @@ Frequently multi-architecture environments (typically x86_64) will run into prob <Instance arch='i686' version='1.0.4-12'/> </Package> -Altogether, this should move policy decisions about package architectures to bundles/base. +Altogether, this should move policy decisions about package architectures +to bundles/base. Client Driver (Plugins) Specific Attributes =========================================== -Not all the attributes that are available in Pkgmgr are honoured by all the client drivers. The following client drivers (plugins) have driver specific attributes: -* [wiki:RPMng RPMng/YUMng] +Not all the attributes that are available in Pkgmgr are honoured by all +the client drivers. The following client drivers (plugins) have driver +specific attributes: + +* :ref:`RPMng <client-tools-yumng>` diff --git a/doc/server/plugins/generators/tcheetah.txt b/doc/server/plugins/generators/tcheetah.txt index a338b0cb3..26b384628 100644 --- a/doc/server/plugins/generators/tcheetah.txt +++ b/doc/server/plugins/generators/tcheetah.txt @@ -48,7 +48,9 @@ The following variables are available for self.metadata: * uuid * password -self.metadata is an instance of the class ClientMetadata of file `Bcfg2/Server/Plugins/Metadata.py <http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/src/lib/Server/Plugins/Metadata.py>`_. +self.metadata is an instance of the class +ClientMetadata of file `Bcfg2/Server/Plugins/Metadata.py +<http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/src/lib/Server/Plugins/Metadata.py>`_. self.properties =============== @@ -69,7 +71,9 @@ Example ``properties.xml``: </host> </Properties> -You may use any of the ElementTree methods to access data in your template. Several examples follow, each producing an identical result on the host 'www.example.com':: +You may use any of the ElementTree methods to access data in your +template. Several examples follow, each producing an identical result +on the host 'www.example.com':: $self.properties.find('host').find('www.example.com').find('rootdev').text $self.properties.find('host').find($self.metadata.hostname).find('rootdev').text @@ -113,7 +117,10 @@ bcfg2/TCheetah/foo/info Output ------ -The following output can be generated with bcfg2-info. Note that probe information is not persistent, hence, it only works when clients directly query the server. For this reason, bcfg2-info output doesn't reflect current client probe state. +The following output can be generated with bcfg2-info. Note that probe +information is not persistent, hence, it only works when clients directly +query the server. For this reason, bcfg2-info output doesn't reflect +current client probe state. .. code-block:: xml @@ -137,7 +144,12 @@ The following output can be generated with bcfg2-info. Note that probe informati Example: Replace the crontab plugin =================================== -In many cases you can use the TCheetah plugin to avoid writing custom plugins in Python. This example replaces the [source:tags/bcfg2_0_8_4/bcfg2/src/lib/Server/Plugins/Crontab.py crontab plugin] (Bcfg2.Server.Plugins.Crontab). This plugin randomizes the time of cron.daily execution with a stable result. Cron.daily is run at a consistent, randomized time between midnight and 7am.:: +In many cases you can use the TCheetah plugin to avoid +writing custom plugins in Python. This example replaces the +[source:tags/bcfg2_0_8_4/bcfg2/src/lib/Server/Plugins/Crontab.py crontab +plugin] (Bcfg2.Server.Plugins.Crontab). This plugin randomizes the time +of cron.daily execution with a stable result. Cron.daily is run at a +consistent, randomized time between midnight and 7am.:: #import random #silent random.seed($self.metadata.hostname) diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt index fbfe42210..8ec4944c9 100644 --- a/doc/server/plugins/grouping/metadata.txt +++ b/doc/server/plugins/grouping/metadata.txt @@ -6,21 +6,31 @@ Metadata ======== -The metadata mechanism has two types of information, client metadata and group metadata. The client metadata describes which top level group a client is associated with.The group metadata describes groups in terms of what bundles and other groups they include. Each aspect grouping and clients' memberships are reflected in the Metadata/groups.xml and Metadata/clients.xml files, respectively. +The metadata mechanism has two types of information, client metadata and +group metadata. The client metadata describes which top level group a +client is associated with.The group metadata describes groups in terms +of what bundles and other groups they include. Each aspect grouping +and clients' memberships are reflected in the Metadata/groups.xml and +Metadata/clients.xml files, respectively. Usage of Groups in Metadata =========================== -Clients are assigned membership of groups in the Metadata descriptions. Clients can be directly assigned to 'profile' or 'public' groups. Client membership of all other groups is by those groups being associated with the profile or public groups. This file can be indirectly modified from clients through use of the -p flag to bcfg2. +Clients are assigned membership of groups in the Metadata +descriptions. Clients can be directly assigned to 'profile' or 'public' +groups. Client membership of all other groups is by those groups being +associated with the profile or public groups. This file can be indirectly +modified from clients through use of the -p flag to bcfg2. -Clients are associated with profile groups in Metadata/clients.xml as shown below. +Clients are associated with profile groups in Metadata/clients.xml as +shown below. Metadata/clients.xml ==================== -The Metadata/clients.xml file contains the mappings of Profile Groups to clients. The -file is just a series of <Client /> tags, each of which describe one host. A sample -file is below: +The Metadata/clients.xml file contains the mappings of Profile Groups +to clients. The file is just a series of <Client /> tags, each of which +describe one host. A sample file is below: .. code-block:: xml @@ -131,9 +141,10 @@ instance, in the above example, a client associated with the Profile Group ``mail-server`` is also a member of the ``apache-server``, ``rhel-as-4-x86``, ``nfs-client``, ``server`` and ``rhel`` groups. -Groups describe clients in terms for abstract, disjoint aspects. Groups can be -combined to form complex descriptions of clients that use configuration commonality -and inheritance. Groups have several attributes, described below: +Groups describe clients in terms for abstract, disjoint aspects. Groups +can be combined to form complex descriptions of clients that use +configuration commonality and inheritance. Groups have several attributes, +described below: Metadata Groups Tag diff --git a/doc/server/plugins/index.txt b/doc/server/plugins/index.txt index 104d4b516..8035f3c31 100644 --- a/doc/server/plugins/index.txt +++ b/doc/server/plugins/index.txt @@ -6,7 +6,8 @@ Plugins ======= -Plugins are the source of all logic used in building a config. They can perform one of several tasks: +Plugins are the source of all logic used in building a config. They can +perform one of several tasks: #. Generating configuration inventory lists for clients #. Generating configuration entry contents for clients @@ -17,12 +18,15 @@ Plugins are the source of all logic used in building a config. They can perform Enabling Plugins ================ -In order for the bcfg2 server to use a plugin, it needs to be listed on the *plugins* line in bcfg2.conf. +In order for the bcfg2 server to use a plugin, it needs to be listed on +the *plugins* line in bcfg2.conf. Default Plugins =============== -The `Bcfg2 repository`_ has the default plugin list currently distributed with Bcfg2: http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/src/lib/Server/Plugins. +The `Bcfg2 repository`_ has the default +plugin list currently distributed with Bcfg2: +http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/src/lib/Server/Plugins. .. _Bcfg2 repository: http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/src/lib/Server/Plugins. @@ -35,7 +39,8 @@ Metadata (Grouping) grouping/* -Each of these plugins has a corresponding subdirectory with the same name in the Bcfg2 repository. +Each of these plugins has a corresponding subdirectory with the same +name in the Bcfg2 repository. Abstract Configuration (Structures) ----------------------------------- @@ -47,7 +52,8 @@ Abstract Configuration (Structures) structures/bundler/index structures/* -Each of these plugins has a corresponding subdirectory with the same name in the Bcfg2 repository. +Each of these plugins has a corresponding subdirectory with the same +name in the Bcfg2 repository. Literal Configuration (Generators) ---------------------------------- @@ -59,7 +65,8 @@ Literal Configuration (Generators) generators/tgenshi/index generators/* -Each of these plugins has a corresponding subdirectory with the same name in the Bcfg2 repository. +Each of these plugins has a corresponding subdirectory with the same +name in the Bcfg2 repository. Statistics Plugins ------------------ @@ -70,7 +77,8 @@ Statistics Plugins statistics/* -DBStats can be enabled by adding it to the plugins line in /etc/bcfg2.conf. +DBStats can be enabled by adding it to the plugins line in +``/etc/bcfg2.conf``. Version Plugins --------------- @@ -84,7 +92,9 @@ Version Plugins Plugin Roles (in 1.0) ===================== -In version 1.0, plugins have been refactored into a series of roles. This are fine-grained plugin capabilities that govern how the server core interacts with plugins. +In version 1.0, plugins have been refactored into a series of roles. This +are fine-grained plugin capabilities that govern how the server core +interacts with plugins. More details can be found in :ref:`server-plugins-plugin-roles` diff --git a/doc/server/plugins/version/bzr.txt b/doc/server/plugins/version/bzr.txt index c86117502..9bb4df712 100644 --- a/doc/server/plugins/version/bzr.txt +++ b/doc/server/plugins/version/bzr.txt @@ -9,7 +9,11 @@ Bzr Why use the Bazaar plugin ========================= -The Bazaar plugin is useful if you would like to track changes to your bcfg2 repository using a `Bazaar <http://bazaar-vcs.org/>`_ backend. Currently, it enables you to get revision information out of your repository for reporting purposes. Future plans are to commit changes to the repo which are made by the server. +The Bazaar plugin is useful if you would like to track changes to +your bcfg2 repository using a `Bazaar <http://bazaar-vcs.org/>`_ +backend. Currently, it enables you to get revision information out +of your repository for reporting purposes. Future plans are to commit +changes to the repo which are made by the server. How to enable the Bazaar plugin =============================== @@ -22,4 +26,7 @@ Simply add "Bzr" to your plugins line in /etc/bcfg2.conf:: Usage notes =========== -Unlike other VCS plugins for BCFG2, the Bazaar plugin checks whether there are uncommitted changes to the repository. If there are, this plugin appends a "+" after the version number. Essentially, this means you're using that version, "plus" some changes. +Unlike other VCS plugins for BCFG2, the Bazaar plugin checks whether +there are uncommitted changes to the repository. If there are, this +plugin appends a "+" after the version number. Essentially, this means +you're using that version, "plus" some changes. diff --git a/doc/server/plugins/version/fossil.txt b/doc/server/plugins/version/fossil.txt index e73979509..7f3a52f5a 100644 --- a/doc/server/plugins/version/fossil.txt +++ b/doc/server/plugins/version/fossil.txt @@ -9,7 +9,11 @@ Fossil Why use the Fossil plugin ========================= -The Fossil plugin is useful if you would like to track changes to your bcfg2 repository using a `Fossil SCM <http://fossil-scm.org>`_ backend. Currently, It enables you to get revision information out of your repository for reporting purposes. Future plans are to commit changes to the repo which are made by the server. +The Fossil plugin is useful if you would like to track changes to +your bcfg2 repository using a `Fossil SCM <http://fossil-scm.org>`_ +backend. Currently, It enables you to get revision information out +of your repository for reporting purposes. Future plans are to commit +changes to the repo which are made by the server. How to enable the Fossil plugin =============================== diff --git a/doc/server/plugins/version/git.txt b/doc/server/plugins/version/git.txt index 0bbef7288..7d901f38d 100644 --- a/doc/server/plugins/version/git.txt +++ b/doc/server/plugins/version/git.txt @@ -9,12 +9,19 @@ Git Why use the Git plugin ====================== -The Git plugin is useful if you would like to track changes to your bcfg2 repository using a `Git <http://git-scm.com/>`_ backend. Currently, It enables you to get revision information out of your repository for reporting purposes. Future plans are to commit changes to the repo which are made by the server. +The Git plugin is useful if you would like to track changes to your bcfg2 +repository using a `Git <http://git-scm.com/>`_ backend. Currently, +It enables you to get revision information out of your repository for +reporting purposes. Future plans are to commit changes to the repo which +are made by the server. How to enable the Git plugin ============================ -The Git plugin uses `Dulwich <http://samba.org/~jelmer/dulwich/>`_ to interface with git repositories. Therefore, you will need to install Dulwich on the bcfg2 server first. Once installed, simply add Git to your plugins line in /etc/bcfg2.conf:: +The Git plugin uses `Dulwich <http://samba.org/~jelmer/dulwich/>`_ to +interface with git repositories. Therefore, you will need to install +Dulwich on the bcfg2 server first. Once installed, simply add Git to +your plugins line in /etc/bcfg2.conf:: [server] plugins = Base,Bundler,Cfg,...,Git diff --git a/doc/server/plugins/version/svn.txt b/doc/server/plugins/version/svn.txt index f1deda3e0..2e26f00c8 100644 --- a/doc/server/plugins/version/svn.txt +++ b/doc/server/plugins/version/svn.txt @@ -9,7 +9,13 @@ Svn Why use the Svn plugin ====================== -The Svn plugin is useful if you would like to track changes to your bcfg2 repository using a `Subversion <http://subversion.tigris.org/>`_ backend. It deprecates the previous Subversion integration mentioned here at ftp://ftp.mcs.anl.gov/pub/bcfg/papers/directing-change-with-bcfg2.pdf. Currently, It enables you to get revision information out of your repository for reporting purposes. Future plans are to commit changes to the repo which are made by the server. +The Svn plugin is useful if you would like to track changes to your +bcfg2 repository using a `Subversion <http://subversion.tigris.org/>`_ +backend. It deprecates the previous Subversion integration mentioned here +at ftp://ftp.mcs.anl.gov/pub/bcfg/papers/directing-change-with-bcfg2.pdf. +Currently, It enables you to get revision information out of your +repository for reporting purposes. Future plans are to commit changes +to the repo which are made by the server. How to enable the Svn plugin ============================ diff --git a/doc/server/reports/index.txt b/doc/server/reports/index.txt index 986efc47d..1360d5ffd 100644 --- a/doc/server/reports/index.txt +++ b/doc/server/reports/index.txt @@ -5,7 +5,9 @@ The Bcfg2 Reporting System ========================== -Bcfg2's reporting system is its killer feature. It allows administrators to gain a broad understanding of the configuration state of their entire environment. It summarizes +Bcfg2's reporting system is its killer feature. It allows administrators +to gain a broad understanding of the configuration state of their entire +environment. It summarizes * Configuration changes and when they were made * Discrepancies between the specification and current client states @@ -15,7 +17,9 @@ Bcfg2's reporting system is its killer feature. It allows administrators to gain * Configuration entries that are not specified * Overall client summaries according to these types -There are two systems, the old system, which builds static reports based on a series of XSLT stylesheets and a new dynamic reporting system that uses django and a database backend. +There are two systems, the old system, which builds static reports based +on a series of XSLT stylesheets and a new dynamic reporting system that +uses django and a database backend. .. toctree:: :maxdepth: 2 diff --git a/doc/server/reports/static.txt b/doc/server/reports/static.txt index 8b984f785..0767a6b2d 100644 --- a/doc/server/reports/static.txt +++ b/doc/server/reports/static.txt @@ -6,49 +6,62 @@ Bcfg2 Static Reporting System ============================= -The Bcfg2 reporting system collects and displays information about the -operation of the Bcfg2 client, and the configuration states of target machines. +The Bcfg2 reporting system collects and displays information about the +operation of the Bcfg2 client, and the configuration states of target +machines. Goals ===== -The reporting system provides an interface to administrators describing a few important tasks +The reporting system provides an interface to administrators describing +a few important tasks * Client configuration state, particularly aspects that do not match the configuration specification. Information about bad and extra configuration elements is included. * Client execution results (a list of configuration elements that were modified) * Client execution performance data (including operation retry counts, and timings for several critical execution regions) -This data can be used to understand the current configuration state of the -entire network, the operations performed by the client, how the configuration changes propagate, and -any reconfiguration operations that have failed. +This data can be used to understand the current configuration state +of the entire network, the operations performed by the client, how the +configuration changes propagate, and any reconfiguration operations that +have failed. Retention Model =============== -The current reporting system stores statistics in an XML data store, by default to {{{<repo>/etc/statistics.xml}}}. It retains either -one or two statistic sets per host. If the client has a clean configuration state, the most recent (clean) record is retained. -If the client has a dirty configuration state, two records are retained. One record is the last -clean record. The other record is the most recent record collected, detailing the incorrect state. +The current reporting system stores statistics in an XML data store, by +default to {{{<repo>/etc/statistics.xml}}}. It retains either one or two +statistic sets per host. If the client has a clean configuration state, +the most recent (clean) record is retained. If the client has a dirty +configuration state, two records are retained. One record is the last +clean record. The other record is the most recent record collected, +detailing the incorrect state. -This retention model, while non-optimal, does manage to persistently record most of the data that users would like. +This retention model, while non-optimal, does manage to persistently +record most of the data that users would like. Setup ===== -In order to configure your bcfg2 server for receiving reports, you will need to list the Statistics plugin in the plugins line of your bcfg2.conf (starting in 1.0). You will also need a [statistics] section in your bcfg2.conf. You can find out more about what goes there in the bcfg2.conf manpage. +In order to configure your bcfg2 server for receiving reports, you +will need to list the Statistics plugin in the plugins line of your +bcfg2.conf (starting in 1.0). You will also need a [statistics] section +in your bcfg2.conf. You can find out more about what goes there in the +bcfg2.conf manpage. Output ====== -Several output reports can be generated from the statistics store with the command line tool {{{bcfg2-build-reports}}}. +Several output reports can be generated from the statistics store with +the command line tool {{{bcfg2-build-reports}}}. * Nodes Digest * Nodes Individual * Overview Statistics * Performance -The data generated by these reports can be delivered by several mechanisms: +The data generated by these reports can be delivered by several +mechanisms: * HTML * Email @@ -57,19 +70,26 @@ The data generated by these reports can be delivered by several mechanisms: Shortcomings and Planned Enhancements ===================================== -When designing the current reporting system, we were overly concerned with the potential explosion in data size over time. -In order to address this, we opted to use the retention scheme described above. This approach has several shortcomings: - -* A comprehensive list of reconfiguration operations (with associated timestamps) isn't retained -* Client results for any given day (except the last one) aren't uniformly retained. This means that inter-client analysis is - difficult, if not impossible - -We plan to move to a database backend to address the dataset size problem and start retaining all information. The move to a -SQL backend will allow many more types of queries to be efficiently processed. It will also make on-demand reports simpler. - -Other sorts of information would also be useful to track. We plan to add the ability to tag a particular configuration -element as security related, and include this in reports. This will aid in the effective prioritization of manual and -failed reconfiguration tasks. +When designing the current reporting system, we were overly concerned with +the potential explosion in data size over time. In order to address this, +we opted to use the retention scheme described above. This approach has +several shortcomings: + +* A comprehensive list of reconfiguration operations (with associated + timestamps) isn't retained +* Client results for any given day (except the last one) aren't uniformly + retained. This means that inter-client analysis is difficult, if + not impossible + +We plan to move to a database backend to address the dataset size +problem and start retaining all information. The move to a SQL backend +will allow many more types of queries to be efficiently processed. It +will also make on-demand reports simpler. + +Other sorts of information would also be useful to track. We plan to +add the ability to tag a particular configuration element as security +related, and include this in reports. This will aid in the effective +prioritization of manual and failed reconfiguration tasks. Capability Goals (posed as questions) ------------------------------------- diff --git a/doc/unsorted/contribute.txt b/doc/unsorted/contribute.txt index e43ed4ad3..a0bdd0ada 100644 --- a/doc/unsorted/contribute.txt +++ b/doc/unsorted/contribute.txt @@ -16,11 +16,20 @@ There are several ways users can contribute to the Bcfg2 project. Development =========== -Send patches to the [wiki:MailingList bcfg mailing list] or create a trac [https://trac.mcs.anl.gov/projects/bcfg2/newticket ticket] with the patch included. In order to submit a ticket via the trac system, you will need to create a session by clicking on the [https://trac.mcs.anl.gov/projects/bcfg2/prefs Preferences] link and filling out/saving changes to the form. In order to be considered for mainline inclusion, patches need to be BSD licensed. The most convenient way to prepare patches is by using svn diff inside of a source tree checked out of subversion. The source tree can be checked out by running:: +Send patches to the [wiki:MailingList bcfg mailing list] or create +a trac [https://trac.mcs.anl.gov/projects/bcfg2/newticket ticket] +with the patch included. In order to submit a ticket via the +trac system, you will need to create a session by clicking on the +[https://trac.mcs.anl.gov/projects/bcfg2/prefs Preferences] link and +filling out/saving changes to the form. In order to be considered for +mainline inclusion, patches need to be BSD licensed. The most convenient +way to prepare patches is by using svn diff inside of a source tree +checked out of subversion. The source tree can be checked out by running:: svn co https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2 -Users wishing to contribute on a regular basis can apply for direct subversion access. Mail the mailing list for details. +Users wishing to contribute on a regular basis can apply for direct +subversion access. Mail the mailing list for details. Several resources for developers exist in the wiki: @@ -32,21 +41,33 @@ Several resources for developers exist in the wiki: * [wiki:LearningPython] * [wiki:UsingRcache] -Bcfg2 is the result of a lot of work by many different people. They are listed on the [wiki:Contributors contributors page.] +Bcfg2 is the result of a lot of work by many different people. They are +listed on the [wiki:Contributors contributors page.] -Feel free to drop in during a [wiki:CodeSprintIdeas code sprint] if you would like to help out with some easier problems. +Feel free to drop in during a [wiki:CodeSprintIdeas code sprint] if you +would like to help out with some easier problems. Testing Prereleases =================== -Before each release, several prereleases will be tagged. It is helpful to have users test these releases (when feasible) because it is hard to replicate the full range of potential reconfiguration situations; between different operating systems, system management tools, and configuration specification variation, there can be large differences between sites. +Before each release, several prereleases will be tagged. It is helpful +to have users test these releases (when feasible) because it is hard to +replicate the full range of potential reconfiguration situations; between +different operating systems, system management tools, and configuration +specification variation, there can be large differences between sites. -See the [wiki:TrackingDevelopmentTrunk] page for a better view of changes in the prereleases. +See the [wiki:TrackingDevelopmentTrunk] page for a better view of changes +in the prereleases. Adding to the Common Repository =============================== -The Bcfg2 common repository is a set of portable examples that new repositories can be based on. This repo has several parts. The first is a series of group definitions that describe a wide range of client systems. The second is a set of portable bundles that have been ported to use these groups. This makes these bundles transparently portable across new client architectures. +The Bcfg2 common repository is a set of portable examples that new +repositories can be based on. This repo has several parts. The first +is a series of group definitions that describe a wide range of client +systems. The second is a set of portable bundles that have been ported +to use these groups. This makes these bundles transparently portable +across new client architectures. This approach has several benefits to users |