diff options
Diffstat (limited to 'doc')
88 files changed, 958 insertions, 1263 deletions
diff --git a/doc/appendix/configuration/mrepo.txt b/doc/appendix/configuration/mrepo.txt index 0633af98e..309cd6779 100644 --- a/doc/appendix/configuration/mrepo.txt +++ b/doc/appendix/configuration/mrepo.txt @@ -15,7 +15,6 @@ takes care of setting up the ISO files, downloading the RPMs, configuring HTTP access and providing PXE/TFTP resources for remote network installations. - Sample mrepo configuration -------------------------- @@ -66,6 +65,6 @@ Sample mrepo configuration Update the repositories ----------------------- -To update your local repository, just lauch the following command :: +:: mrepo -ug diff --git a/doc/appendix/contributors.txt b/doc/appendix/contributors.txt index 9f2c18115..eaf4aa29a 100644 --- a/doc/appendix/contributors.txt +++ b/doc/appendix/contributors.txt @@ -1,6 +1,6 @@ .. -*- mode: rst -*- -.. _AUTHORS: http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/AUTHORS +.. _AUTHORS: http://trac.mcs.anl.gov/projects/bcfg2/browser/AUTHORS .. _MCS: http://www.mcs.anl.gov/ .. _appendix-contributors: diff --git a/doc/appendix/guides/authentication.txt b/doc/appendix/guides/authentication.txt index 13b797625..0a324b718 100644 --- a/doc/appendix/guides/authentication.txt +++ b/doc/appendix/guides/authentication.txt @@ -1,6 +1,6 @@ .. -*- mode: rst -*- -.. _guide-authentication: +.. _appendix-guides-authentication: ============== Authentication @@ -14,7 +14,7 @@ Scenarios Default settings work well; machines do not float, and a per-client password is not required. -2. :ref:`NAT Howto nat_howto` +2. :ref:`appendix-guides-nat_howto` * Build client records in advance with ``bcfg2-admin``, setting a uuid for each new client. @@ -33,7 +33,7 @@ Building bcfg2.conf automatically ================================= This is a TCheetah template that automatically constructs per-client -`bcfg2.conf` from the per-client metadata:: +bcfg2.conf from the per-client metadata:: [communication] protocol = xmlrpc/ssl @@ -43,14 +43,14 @@ This is a TCheetah template that automatically constructs per-client #if $self.metadata.password != None password = $self.metadata.password #else - password = my-password-foobar + password = my-password-foobat #end if [components] bcfg2 = https://localhost:6789 In this setup, this will cause any clients that have uuids established -to be set to use them in `bcfg2.conf`. It will also cause any clients +to be set to use them in ``bcfg2.conf``. It will also cause any clients with passwords set to use them instead of the global password. How Authentication Works diff --git a/doc/appendix/guides/centos.txt b/doc/appendix/guides/centos.txt index 91c1f268f..1e3c90156 100644 --- a/doc/appendix/guides/centos.txt +++ b/doc/appendix/guides/centos.txt @@ -2,7 +2,7 @@ .. _EPEL: http://fedoraproject.org/wiki/EPEL -.. _guide-centos: +.. _appendix-guides-centos: ===================== Quickstart for CentOS diff --git a/doc/appendix/guides/converging_rhel5.txt b/doc/appendix/guides/converging_rhel5.txt index 9d508e5e4..7581d307f 100644 --- a/doc/appendix/guides/converging_rhel5.txt +++ b/doc/appendix/guides/converging_rhel5.txt @@ -1,6 +1,6 @@ .. -*- mode: rst -*- -.. _unsorted-converging_rhel5: +.. _appendix-guides-converging_rhel5: ====================================== Converging on Verification with RHEL 5 @@ -18,25 +18,29 @@ Unmanaged entries * Package (top-level) - #. Enable the "Packages" plugin in {{{/etc/bcfg2.conf}}}, and configure the Yum repositories in {{{/var/lib/bcfg2/Packages/config.xml}}}. + #. Enable the "Packages" plugin in ``/etc/bcfg2.conf``, and configure + the Yum repositories in ``/var/lib/bcfg2/Packages/config.xml``. #. If a package is unwanted, remove it:: sudo yum remove PACKAGE - #. Otherwise, add {{{<Package name="PACKAGE" />}}} to the Base or Bundler configuration. + #. Otherwise, add ``<Package name="PACKAGE" />`` to the Base or Bundler configuration. * Package (dependency) - #. Ensure the Yum repository sources configured in {{{/var/lib/bcfg2/Packages/config.xml}}} are correct. - #. Ensure the Yum repositories themselves are up-to-date with the main package and dependencies. + #. Ensure the Yum repository sources configured in + ``/var/lib/bcfg2/Packages/config.xml`` are correct. + #. Ensure the Yum repositories themselves are up-to-date with the main + package and dependencies. #. Rebuild the Packages plugin cache:: bcfg2-admin xcmd Packages.Refresh * Service - #. Add {{{<Service name="SERVICE" />}}} to the Base or Bundler configuration. - #. Add {{{<Service name="SERVICE" status="on" type="chkconfig" />}}} to {{{/var/lib/bcfg2/Rules/services.xml}}}. + #. Add ``<Service name="SERVICE" />`` to the Base or Bundler configuration. + #. Add ``<Service name="SERVICE" status="on" type="chkconfig" />`` to + ``/var/lib/bcfg2/Rules/services.xml``. Incorrect entries ================= @@ -46,13 +50,17 @@ For a "Package" * Failed RPM verification - #. Run {{{rpm -V PACKAGE}}} - #. Add configuration files (the ones with "c" next to them in the verification output) to {{{/var/lib/bcfg2/Cfg/}}}. + #. Run ``rpm -V PACKAGE`` + #. Add configuration files (the ones with "c" next to them in the + verification output) to ``/var/lib/bcfg2/Cfg/``. - * For example, {{{/etc/motd}}} to {{{/var/lib/bcfg2/Cfg/etc/motd/motd}}}. Yes, there is an extra directory level named after the file. + * For example, ``/etc/motd`` to ``/var/lib/bcfg2/Cfg/etc/motd/motd``. + Yes, there is an extra directory level named after the file. - #. Specify configuration files as {{{<Path name='PATH' />}}} in the Base or Bundler configuration. - #. Add directories to {{{/var/lib/bcfg2/Rules/directories.xml}}}. For example: + #. Specify configuration files as ``<Path name='PATH' />`` in the Base + or Bundler configuration. + #. Add directories to ``/var/lib/bcfg2/Rules/directories.xml``. For + example: .. code-block:: xml @@ -65,8 +73,9 @@ For a "Package" * Option A: Explicitly list the instances - #. Drop the {{{<Package />}}} from the Base or Bundler configuration. - #. Add an explicit {{{<BoundPackage>}}} and {{{<Instance />}}} configuration to a new Bundle, like the following: + #. Drop the ``<Package />`` from the Base or Bundler configuration. + #. Add an explicit ``<BoundPackage>`` and ``<Instance />`` configuration + to a new Bundle, like the following: .. code-block:: xml @@ -78,22 +87,25 @@ For a "Package" </BoundPackage> </Bundle> - #. Add the bundle to the applicable groups in {{{/var/lib/bcfg2/Metadata/groups.xml}}}. + #. Add the bundle to the applicable groups in + ``/var/lib/bcfg2/Metadata/groups.xml``. * Option B: Disable verification of the package - #. Add {{{pkg_checks="false"}}} to the {{{<Package />}}} tag. + #. Add ``pkg_checks="false"`` to the ``<Package />`` tag. For a "Path" ------------------- - * Unclear verification problem (no details from BCFG2) + * Unclear verification problem (no details from Bcfg2) - 1. Run {{{bcfg2 -vqI}}} to see detailed verification issues (but deny any suggested actions). + 1. Run ``bcfg2 -vqI`` to see detailed verification issues (but deny + any suggested actions). * Permissions mismatch - 1. Create an {{{info.xml}}} file in the same directory as the configuration file. Example: + 1. Create an ``info.xml`` file in the same directory as the + configuration file. Example: .. code-block:: xml diff --git a/doc/appendix/guides/fedora.txt b/doc/appendix/guides/fedora.txt index f3a5a3929..d8d3b1b34 100644 --- a/doc/appendix/guides/fedora.txt +++ b/doc/appendix/guides/fedora.txt @@ -470,8 +470,3 @@ The first commit can be the empty or the allready populated directory:: While running ``bcfg2-info`` the following line will show up:: Initialized git plugin with git directory = /var/lib/bcfg2/.git - - - - - diff --git a/doc/appendix/guides/gentoo.txt b/doc/appendix/guides/gentoo.txt index 023e6ac24..e818364ce 100644 --- a/doc/appendix/guides/gentoo.txt +++ b/doc/appendix/guides/gentoo.txt @@ -1,6 +1,6 @@ .. -*- mode: rst -*- -.. _guide-gentoo: +.. _appendix-guides-gentoo: ====== Gentoo @@ -23,8 +23,8 @@ should still work provided that you have a reasonably up to date Python; try adding `app-admin/bcfg2 ~*` to your `/etc/portage/package.keywords` file. -If you don’t use portage to install Bcfg2, you’ll want to make sure you -have all the prerequisites installed first. For a server, you’ll need: +If you don't use portage to install Bcfg2, you'll want to make sure you +have all the prerequisites installed first. For a server, you'll need: * ``app-admin/gamin`` or ``app-admin/fam`` * ``dev-python/lxml`` @@ -37,7 +37,7 @@ Package Repository ================== You’ll need (to make) at least one archive of binary packages. The -Portage driver calls ``emerge`` with the ``–getbinpkgonly`` option. See +Portage driver calls ``emerge`` with the ``-getbinpkgonly`` option. See :manpage:`make.conf(5)` and :manpage:`emerge(1)` manpages, specifically the *PORTAGE_BINHOST* environment variable. @@ -52,7 +52,7 @@ present state of the system by using the quickpkg utility. For example: for pkg in `equery -q l` ; do quickpkg "=$pkg" ; done -…will leave you with a complete archive of all the packages on your +...will leave you with a complete archive of all the packages on your system in ``/usr/portage/packages/All``, which you can then move to your ftp server. @@ -60,7 +60,7 @@ Cataloging Packages In Your Repository -------------------------------------- Once you have a set of packages, you will need to create a catalog for -them in ``/var/lib/bcfg2/Pkgmgr``. Here’s a template: +them in ``/var/lib/bcfg2/Pkgmgr``. Here's a template: .. code-block:: xml @@ -70,7 +70,7 @@ them in ``/var/lib/bcfg2/Pkgmgr``. Here’s a template: </Group> </PackageList> -…and a partially filled-out example, for our local Gentoo/VMware build: +...and a partially filled-out example, for our local Gentoo/VMware build: .. code-block:: xml @@ -82,17 +82,17 @@ them in ``/var/lib/bcfg2/Pkgmgr``. Here’s a template: </Group> </PackageList> -The `<Group>` name (in our example, “gentoo-200701-vmware”) should +The `<Group>` name (in our example, "gentoo-200701-vmware") should be included by any host which will draw its packages from this list. Our collection of packages for this class of machines is at the listed URI, and we only have one collection of packages for this batch of machines so -in our case the `priority` doesn’t really matter, we’ve set it to `0`. +in our case the `priority` doesn’t really matter, we've set it to `0`. Notice that package name fields are in `CAT/TITLE` format. Here is a hack which will generate a list of Package lines from -a system’s database of installed packages, especially useful in -conjunction with the `quickpkg` example above: +a system's database of installed packages, especially useful in +conjunction with the ``quickpkg`` example above: .. code-block:: sh @@ -123,14 +123,14 @@ Pitfalls Package Verification Issues --------------------------- -As of this writing (2007/01/31), we’re aware of a number of packages +As of this writing (2007/01/31), we're aware of a number of packages marked stable in the Gentoo x86 tree which, for one reason or another, -consistently fail to verify cleanly under `equery check`. In some cases -(pam, openldap), files which don’t (ever) exist on the system are +consistently fail to verify cleanly under ``equery check``. In some cases +(pam, openldap), files which don't (ever) exist on the system are nonetheless recorded in the package database; in some (python, Bcfg2, ahem), whole classes of files (.pyc and .pyo files) consistently fail their md5sum checks; and in others, the problem appears to be a -discrepancy in the way that symlinks are created vs. the way they’re +discrepancy in the way that symlinks are created vs. the way they're recorded in the database. For example, in the OpenSSH package, /usr/bin/slogin is a symlink to ./ssh, but equery expects it to point to an unadorned ssh. An analogous situation exists with their manpages, @@ -147,13 +147,13 @@ leading to noise like this:: We can ignore the lines for ``ssh_config`` and ``sshd_config``; those will be caught by Bcfg2 as registered config files and handled appropriately. -Because Bcfg2 relies on the client system’s native package reporting +Because Bcfg2 relies on the client system's native package reporting tool to judge the state of installed packages, complaints like these about trivial or intractable verification failures can trigger unnecessary bundle reinstalls when the Bcfg2 client runs. Bcfg2 will catch on after a -pass or two that the situation isn’t getting any better with repeated -package installs, stop trying, and list those packages as “bad” in -the client system’s statistics. +pass or two that the situation isn't getting any better with repeated +package installs, stop trying, and list those packages as "bad" in +the client system's statistics. Aside from filing bugs with the Gentoo package maintainers, your narrator has been unable to come up with a good approach to this. Maybe write a @@ -171,7 +171,7 @@ during normal runtime. This can lead to trouble during verification and package installation, for example when ``/boot/grub/grub.conf`` turns up missing. The simplest way around this might just be to ensure that ``/boot`` is mounted whenever you run Bcfg2, possibly wrapping Bcfg2 -in a script for the purpose. I’ve also thought about adding *Action* +in a script for the purpose. I've also thought about adding *Action* clauses to bundles for grub and our kernel packages, which would mount ``/boot`` before the bundle installs and unmount it afterward, but this -doesn’t get around the problem of those packages flunking verification. +doesn't get around the problem of those packages flunking verification. diff --git a/doc/appendix/guides/nat_howto.txt b/doc/appendix/guides/nat_howto.txt index 131c0c533..818d3e644 100644 --- a/doc/appendix/guides/nat_howto.txt +++ b/doc/appendix/guides/nat_howto.txt @@ -1,56 +1,86 @@ .. -*- mode: rst -*- -.. _unsorted-nat_howto: +.. _appendix-guides-nat_howto: ========= NAT HOWTO ========= -This page describes how to setup bcfg2 to properly function with a collection of clients behind NAT. It describes the issues, how the underlying portions of the bcfg2 system function, and how to correctly setup client metadata to cope with this environment. +This page describes how to setup Bcfg2 to properly function with a +collection of clients behind NAT. It describes the issues, how the +underlying portions of the Bcfg2 system function, and how to correctly +setup client metadata to cope with this environment. Issues ====== -Bcfg2, by default, uses ip address lookup to determine the identity of a client that has connected. This process doesn't work properly in the case of NATted hosts, because all requests from these clients come from the same external address when connecting to the server. +Bcfg2, by default, uses ip address lookup to determine the identity of +a client that has connected. This process doesn't work properly in the +case of NAT'ed hosts, because all requests from these clients come from +the same external address when connecting to the server. -These client identification issues will manifest themselves in a number of ways: +These client identification issues will manifest themselves in a number +of ways: * Inability to setup discrete clients with different profiles * Incorrect sharing of probe results across clients in the same NAT pool -* Inability to bootstrap clients properly when client data is not predefined +* Inability to bootstrap clients properly when client data is not + predefined Architectural Issues ==================== -Client identification is performed as the beginning of each client/server interaction. As of 0.9.3pre3, client identification via IP address can be completely short-circuited through the use of a client uuid. Setup of client uuids requires actions of both the client and server. On the server side, the client uuid must be added to the client record in Metadata/clients.xml. This attribute allows the server to use the user part of the authentication to resolve the client's metadata. Also, either the location attribute should be set to floating, or the IP address of the NAT must be reflected in the address attribute. -Once added, the Client entry in clients.xml will look like: +Client identification is performed at the beginning of each client/server +interaction. As of 0.9.3, client identification via IP address can be +completely short-circuited through the use of a client uuid. Setup of +client uuids requires actions of both the client and server. On the +server side, the client uuid must be added to the client record in +``Metadata/clients.xml``. This attribute allows the server to use the +user part of the authentication to resolve the client's metadata. Also, +either the location attribute should be set to floating, or the IP address +of the NAT must be reflected in the address attribute. Once added, +the Client entry in clients.xml will look something like this: .. code-block:: xml <Client profile="desktop" name="test1" pingable="N" uuid='9001ec29-1531-4b16-8198-a71bea093d0a' location='floating'/> -Alternatively, the Client entry can be setup like: +Alternatively, the Client entry can be setup like this: .. code-block:: xml <Client profile="desktop" name="test1" pingable="N" uuid='9001ec29-1531-4b16-8198-a71bea093d0a' address='ip-address-of-NAT'/> -The difference between these definitions is explained in detail on the [wiki:Authentication] page, but in short, the second form requires that the client access the server from the NAT address, while the first form allows it to connect from any address provided it uses the proper uuid. (Client identification is orthogonal to the use of per-client passwords; this can be set in addition to the attributes above.) +The difference between these definitions is explained in detail in the +:ref:`appendix-guides-authentication` section, but in short, the second +form requires that the client access the server from the NAT address, +while the first form allows it to connect from any address provided it +uses the proper uuid. (Client identification is orthogonal to the use +of per-client passwords; this can be set in addition to the attributes +above.) -Once this setup is done, each client must be configured to use the proper uuid upon any server interaction. This can be done using either the command line argument -u, or the setting "user" in the "communication" section of /etc/bcfg2.conf. +Once this setup is done, each client must be configured to use the proper +uuid upon any server interaction. This can be done using either the +command line argument -u, or the setting "user" in the "communication" +section of ``/etc/bcfg2.conf``. UUID Choice =========== -When determining client UUIDs, one must take care to ensure that UUIDs are unique to the client. Any hardware-specific attribute, like a hash of a mac address would be sufficient. Alternatively, if a local hostname is unique, it may be used as well. +When determining client UUIDs, one must take care to ensure that UUIDs +are unique to the client. Any hardware-specific attribute, like a hash +of a mac address would be sufficient. Alternatively, if a local hostname +is unique, it may be used as well. Automated Client Bootstrapping ============================== -Automated setup of new clients from behind NAT works by using the common password. For example:: +Automated setup of new clients from behind NAT works by using the common +password. For example:: /usr/sbin/bcfg2 -u ubik3 -p desktop -x <password> -It is not possible at this time to do automated setup without setting up a pre-shared per-client key. +It is not possible at this time to do automated setup without setting +up a pre-shared per-client key. diff --git a/doc/appendix/guides/ubuntu.txt b/doc/appendix/guides/ubuntu.txt index a4790ffed..595005018 100644 --- a/doc/appendix/guides/ubuntu.txt +++ b/doc/appendix/guides/ubuntu.txt @@ -1,6 +1,6 @@ .. -*- mode: rst -*- -.. _guide-ubuntu: +.. _appendix-guides-ubuntu: ====== Ubuntu @@ -8,9 +8,9 @@ Ubuntu .. note:: - This particular how to was done on lucid, but should apply to any - other `stable`__ version of Ubuntu. - + This particular how to was done on lucid, but should apply to any + other `stable`__ version of Ubuntu. + __ ubuntu-releases_ .. _ubuntu-releases: https://wiki.ubuntu.com/Releases @@ -60,9 +60,9 @@ allows you to automate this process.:: 6: Gentoo 7: FreeBSD : 5 - Generating a 1024 bit RSA private key - .......................................................................................+++ - ...++++++ + Generating a 2048 bit RSA private key + ......................................................................................+++ + ...+++ writing new private key to '/etc/bcfg2.key' ----- Signature ok diff --git a/doc/appendix/guides/using-bcfg2-info.txt b/doc/appendix/guides/using-bcfg2-info.txt index 5f77a3c70..b2354652f 100644 --- a/doc/appendix/guides/using-bcfg2-info.txt +++ b/doc/appendix/guides/using-bcfg2-info.txt @@ -1,6 +1,6 @@ .. -*- mode: rst -*- -.. _guide-using_bcfg2_info: +.. _appendix-guides-using_bcfg2_info: ================ Using bcfg2-info diff --git a/doc/appendix/guides/using-bcfg2-with-centos.txt b/doc/appendix/guides/using-bcfg2-with-centos.txt index 7c452f422..93875d4c5 100644 --- a/doc/appendix/guides/using-bcfg2-with-centos.txt +++ b/doc/appendix/guides/using-bcfg2-with-centos.txt @@ -43,9 +43,9 @@ Now you can install the rest of the prerequisites:: Build Packages from source ########################## -* After installing subversion, check out a copy of trunk :: +* After installing git, clone the master branch:: - [root@centos redhat]# svn co https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2 + [root@centos redhat]# git clone git://git.mcs.anl.gov/bcfg2.git * Install the ``fedora-packager`` package :: diff --git a/doc/appendix/guides/vcs.txt b/doc/appendix/guides/vcs.txt index 207337c30..6c2879a65 100644 --- a/doc/appendix/guides/vcs.txt +++ b/doc/appendix/guides/vcs.txt @@ -1,28 +1,23 @@ .. -*- mode: rst -*- -.. _guide-vcs: +.. _appendix-guides-vcs: ======================= Version control systems ======================= -The sections in this guide do only cover the basics steps in the setup -of the different version control system for the usage with the Bcfg2 -plugin support. More more details about +The sections in this guide only cover the basics steps in the setup of +the different version control systems for usage with the Bcfg2. Git === .. _Git tutorial: http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html -Adding the :ref:`server-plugins-version-git` plugins can preserve -versioning information. The first step is to add **Git** to your -plugin line:: - - plugins = Base,Bundler,Cfg,...,Git - -For tracking the configuration files in the ``/var/lib/bcfg2`` -directory a git repository need to be established:: +Adding the :ref:`server-plugins-version-git` plugin will allow you to +store version information in the statistics database. For tracking the +configuration files in the ``/var/lib/bcfg2`` directory a git repository +needs to be established:: git init @@ -38,12 +33,11 @@ While running ``bcfg2-info`` the following line will show up:: Mercurial ========= -For the :ref:`server-plugins-version-hg` plugin are the same changes -needed as for git. :: +The :ref:`server-plugins-version-hg` plugin also allows you to store +version information in the statistics database. - plugins = Base,Bundler,Cfg,...,Mercurial - -The repository must be initialized:: +To use mercurial to track your configuration files, the repository must +be initialized:: hg init @@ -68,12 +62,11 @@ While running ``bcfg2-info`` the following line will show up:: Darcs ===== -If you wish to use the :ref:`server-plugins-version-darcs` plugin an -entry has to be made in the ``bcfg2.conf`` file.:: - - plugins = Base,Bundler,Cfg,...,Darcs +The :ref:`server-plugins-version-darcs` plugin also allows you to store +version information in the statistics database. -The dracs repository must be initialized:: +To use darcs to track your configuration files, the repository must +be initialized:: darcs initialize @@ -87,7 +80,8 @@ darcs will ask you to enter your e-mail address. you@example.com END_ENTRY -All files in the ``/var/lib/bcfg2`` should be added to darcs now:: +All files in the ``/var/lib/bcfg2`` directory should be added to darcs +now:: darcs add * @@ -102,8 +96,8 @@ While running ``bcfg2-info`` the following line will show up:: Cvs === -If you wish to use the :ref:`server-plugins-version-darcs` plugin an -entry has to be made in the ``bcfg2.conf`` file.:: +The :ref:`server-plugins-version-cvs` plugin also allows you to store +version information in the statistics database. plugins = Base,Bundler,Cfg,...,Cvs diff --git a/doc/appendix/guides/web-reports.txt b/doc/appendix/guides/web-reports-install.txt index 9eadfb678..af2e240fa 100644 --- a/doc/appendix/guides/web-reports.txt +++ b/doc/appendix/guides/web-reports-install.txt @@ -5,7 +5,7 @@ .. This is combination of the Ubuntu guide and the Centos guide for installing the web reports. -.. _web-reports: +.. _appendix-guides-web-reports-install: ================================== Dynamic (web) Reports installation @@ -180,5 +180,5 @@ then have something like this:: Restart apache and point a browser to your Bcfg2 server. -If using sqlite be sure the sql database file and directory containing the -database are writable to apache. +If using sqlite be sure the sql database file and directory containing +the database are writable to apache. diff --git a/doc/appendix/index.txt b/doc/appendix/index.txt index 1bac69a3d..407119e24 100644 --- a/doc/appendix/index.txt +++ b/doc/appendix/index.txt @@ -6,14 +6,6 @@ Appendix ======== -Bcfg2 is based on a client-server architecture. The client is -responsible for interpreting (but not processing) the configuration -served by the server. This configuration is literal, so no local -process is required. After completion of the configuration process, -the client uploads a set of statistics to the server. This section -will describe the goals and then the architecture motivated by it. - - .. toctree:: :maxdepth: 2 diff --git a/doc/appendix/tools.txt b/doc/appendix/tools.txt index 040823504..1d7a8dd90 100644 --- a/doc/appendix/tools.txt +++ b/doc/appendix/tools.txt @@ -11,4 +11,4 @@ can help you to maintain your Bcfg2 configuration, to make the initial setup easier, or to do some other tasks. -http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/tools +http://trac.mcs.anl.gov/projects/bcfg2/browser/tools diff --git a/doc/architecture/index.txt b/doc/architecture/index.txt index d5e034d34..742035f8d 100644 --- a/doc/architecture/index.txt +++ b/doc/architecture/index.txt @@ -2,16 +2,16 @@ .. _architecture-index: -====================== -Architecture in Detail -====================== +=========================== +Detailed Bcfg2 Architecture +=========================== -Bcfg2 is based on a client-server architecture. The client is -responsible for interpreting (but not processing) the configuration -served by the server. This configuration is literal, so no local -process is required. After completion of the configuration process, -the client uploads a set of statistics to the server. This section -will describe the goals and then the architecture motivated by it. +Bcfg2 is based on a client-server architecture. The client is responsible +for interpreting (but not processing) the configuration served by the +server. This configuration is literal, so no local process is required. +After completion of the configuration process, the client uploads a set +of statistics to the server. This section will describe the goals and +then the architecture motivated by it. .. toctree:: diff --git a/doc/bcfg2.pdf b/doc/bcfg2.pdf Binary files differdeleted file mode 100644 index 4a34a5352..000000000 --- a/doc/bcfg2.pdf +++ /dev/null diff --git a/doc/client/tools/blast.txt b/doc/client/tools/blast.txt deleted file mode 100644 index 14eb53124..000000000 --- a/doc/client/tools/blast.txt +++ /dev/null @@ -1,10 +0,0 @@ -.. -*- mode: rst -*- - -.. _client-tools-blast: - -===== -Blast -===== - -Blastwave Packages. This tool driver is for blastwave packages on -solaris. diff --git a/doc/client/tools/chkconfig.txt b/doc/client/tools/chkconfig.txt deleted file mode 100644 index 35cc0969e..000000000 --- a/doc/client/tools/chkconfig.txt +++ /dev/null @@ -1,15 +0,0 @@ -.. -*- mode: rst -*- - -.. _client-tools-chkconfig: - -========= -Chkconfig -========= - -Tool to manage services (primarily on Red Hat based distros). - -.. note:: Start and stop are standard arguments, but the one for reload - isn't consistent across services. You can specify which argument - to use with the `restart` property in Service tags. Example: - ``<Service name="ftp" restart="condrestart" status="on" - type="chkconfig">`` diff --git a/doc/client/tools/debinit.txt b/doc/client/tools/debinit.txt deleted file mode 100644 index 33d20f89c..000000000 --- a/doc/client/tools/debinit.txt +++ /dev/null @@ -1,9 +0,0 @@ -.. -*- mode: rst -*- - -.. _client-tools-debinit: - -======= -DebInit -======= - -Debian Service Support; exec's update-rc.d to configure services. diff --git a/doc/client/tools/encap.txt b/doc/client/tools/encap.txt deleted file mode 100644 index 40508ac7a..000000000 --- a/doc/client/tools/encap.txt +++ /dev/null @@ -1,9 +0,0 @@ -.. -*- mode: rst -*- - -.. _client-tools-encap: - -===== -Encap -===== - -`Encap <http://www.encap.org>`_ Packages. diff --git a/doc/client/tools/freebsdinit.txt b/doc/client/tools/freebsdinit.txt deleted file mode 100644 index 7df2518bc..000000000 --- a/doc/client/tools/freebsdinit.txt +++ /dev/null @@ -1,9 +0,0 @@ -.. -*- mode: rst -*- - -.. _client-tools-freebsdinit: - -=========== -FreeBSDInit -=========== - -FreeBSD Service Support. Only bundle updates will work. diff --git a/doc/client/tools/freebsdpackage.txt b/doc/client/tools/freebsdpackage.txt deleted file mode 100644 index a460fb41c..000000000 --- a/doc/client/tools/freebsdpackage.txt +++ /dev/null @@ -1,10 +0,0 @@ -.. -*- mode: rst -*- - -.. _client-tools-freebsdpackage: - -============== -FreeBSDPackage -============== - -FreeBSD Packages. Verifies packages and their version numbers but can't -install packages. diff --git a/doc/client/tools/index.txt b/doc/client/tools/index.txt index 7f6e6b667..9bec46316 100644 --- a/doc/client/tools/index.txt +++ b/doc/client/tools/index.txt @@ -2,31 +2,154 @@ .. _client-tools-index: -Available client tools -====================== - -Client tool drivers allow Bcfg2 to execute configuration operations -by interfacing with platform and distribution specific tools. - -Tool drivers handle any reconfiguration or verification operation. -So far we have tools that primarily deal with packaging systems -and service management. The POSIX tool also handles file system -and permissions/groups operations. To write your own tool driver, -to handle a new packaging format, or new service architecture see -:ref:`development-client-driver`. - -When the Bcfg2 client is run, it attempts to instantiate each of -these drivers. The succeeding list of drivers are printed as a -debug message after this process has completed. Drivers can -supercede one another, for example, the Yum driver conflicts (and -unloads) the RPM driver. This behavior can be overridden by running -the Bcfg2 client with the ``-D`` flag. This flag takes a colon -delimited list of drivers to use on the system. +Client Tool Drivers +=================== + +Client tool drivers allow Bcfg2 to execute configuration operations by +interfacing with platform and distribution specific tools. + +Tool drivers handle any reconfiguration or verification operation. So +far we have tools that primarily deal with packaging systems and service +management. The POSIX tool also handles file system and permissions/groups +operations. + +To write your own tool driver, to handle a new packaging format, or new +service architecture see :ref:`development-index-writingtooldrivers` + +When the Bcfg2 client is run, it attempts to instantiate each of these +drivers. The succeeding list of drivers are printed as a debug message +after this process has completed. Drivers can supercede one another, +for example, the Yum driver conflicts (and unloads) the RPM driver. This +behavior can be overridden by running the Bcfg2 client with the ``-D`` +flag. This flag takes a colon delimited list of drivers to use on +the system. Currently these are the tool drivers that are distributed with Bcfg2: -.. toctree:: - :maxdepth: 1 - :glob: +Action +------ + +Pre and post-install tests and actions. This driver executes commands +and supplies status information to the Bcfg2 server via the statistics +mechanism. It can also be used to prevent bundle installation when +pre-conditions are not met. See the UsingActions page for more details. + +APT +--- + +Debian Packages. This tool driver is used to handle packages on dpkg +based systems and employs the "apt" executable. Extra information can be +found at :ref:`client-tools-apt`. + +Blast +----- + +Blastwave Packages. This tool driver is for blastwave packages on solaris + +Chkconfig +--------- + +Tool to manage services (primarily on Redhat based distros). + +.. note:: Start and stop are standard arguments, but the one for reload + isn't consistent across services. You can specify which argument + to use with the `restart` property in Service tags. Example: + ``<Service name="ftp" restart="condrestart" status="on" + type="chkconfig">`` + +DebInit +------- + +Debian Service Support; exec's update-rc.d to configure services. + +Encap +----- + +`Encap <http://www.encap.org>`_ Packages. + +FreeBSDInit +----------- + +FreeBSD Service Support. Only bundle updates will work. + +FreeBSDPackage +-------------- + +FreeBSD Packages. Verifies packages and their version numbers but can't +install packages. + +launchd +------- + +Mac OS X Services. To use this tool, you must maintain a standard launch +daemon .plist file in ``/Library/LaunchDaemons/`` (example ssh.plist) +and setup a ``<Service name="com.openssh.sshd" type="launchd" status="on" +/>`` entry in your config to load or unload the service. Note the name +is the ''Label'' specified inside of the .plist file + +Portage +------- + +Support for Gentoo Packages. + +POSIX +----- + +Files and Permissions are handled by the POSIX driver. Usage well +documented other places. + +RcUpdate +-------- + +Uses the rc-update executable to manage services on distributions such +as Gentoo. + +RPM +--- + +.. warning:: Deprecated in favor of :ref:`RPMng <client-tools-yumng>` + +Executes rpm to manage packages most often on redhat based systems. + +RPMng +----- + +Next-generation RPM tool. Handles RPM sublties like epoch and +prelinking and 64-bit platforms better than the RPM client +tool. :ref:`client-tools-yumng` + +SMF +--- + +Solaris Service Support. + +Example legacy run service (lrc): + +.. code-block:: xml + + <BoundService name='/etc/rc2_d/S47pppd' FMRI='lrc:/etc/rc2_d/S47pppd' status='off' type='smf'/> + +SYSV +---- + +Handles System V Packaging format that is available on Solaris. + +Upstart +------- + +Upstart service support. Uses `Upstart`_ to configure services. + +.. _Upstart: http://upstart.ubuntu.com/ + +Yum +--- + +.. warning:: Deprecated in favor of :ref:`YUMng <client-tools-yumng>` + +Handles RPMs using the YUM package manager. + +YUMng +----- - * +Handles RPMs using the YUM package manager. Handles sublties better than +the Yum client tool. :ref:`client-tools-yumng` diff --git a/doc/client/tools/launchd.txt b/doc/client/tools/launchd.txt deleted file mode 100644 index 59a872297..000000000 --- a/doc/client/tools/launchd.txt +++ /dev/null @@ -1,13 +0,0 @@ -.. -*- mode: rst -*- - -.. _client-tools-launchd: - -======= -launchd -======= - -Mac OS X Services. To use this tool, you must maintain a standard launch -daemon .plist file in ``/Library/LaunchDaemons/`` (example ssh.plist) -and setup a ``<Service name="com.openssh.sshd" type="launchd" status="on" -/>`` entry in your config to load or unload the service. Note the name -is the ''Label'' specified inside of the .plist file diff --git a/doc/client/tools/portage.txt b/doc/client/tools/portage.txt deleted file mode 100644 index 7a91408b1..000000000 --- a/doc/client/tools/portage.txt +++ /dev/null @@ -1,9 +0,0 @@ -.. -*- mode: rst -*- - -.. _client-tools-portage: - -======= -Portage -======= - -Support for Gentoo Packages. diff --git a/doc/client/tools/posix.txt b/doc/client/tools/posix.txt deleted file mode 100644 index c4da38332..000000000 --- a/doc/client/tools/posix.txt +++ /dev/null @@ -1,10 +0,0 @@ -.. -*- mode: rst -*- - -.. _client-tools-posix: - -===== -POSIX -===== - -Files and Permissions are handled by the POSIX driver. Usage well -documented other places. diff --git a/doc/client/tools/rcupdate.txt b/doc/client/tools/rcupdate.txt deleted file mode 100644 index 4547d3b39..000000000 --- a/doc/client/tools/rcupdate.txt +++ /dev/null @@ -1,10 +0,0 @@ -.. -*- mode: rst -*- - -.. _client-tools-rcupdate: - -======== -RcUpdate -======== - -Uses the rc-update executable to manage services on distributions such -as Gentoo. diff --git a/doc/client/tools/rpm.txt b/doc/client/tools/rpm.txt deleted file mode 100644 index 17d367b55..000000000 --- a/doc/client/tools/rpm.txt +++ /dev/null @@ -1,11 +0,0 @@ -.. -*- mode: rst -*- - -.. _client-tools-rpm: - -=== -RPM -=== - -.. warning:: Deprecated in favor of :ref:`RPMng <client-tools-yumng>` - -Executes rpm to manage packages most often on redhat based systems. diff --git a/doc/client/tools/rpmng.txt b/doc/client/tools/rpmng.txt deleted file mode 100644 index c6d6cddf1..000000000 --- a/doc/client/tools/rpmng.txt +++ /dev/null @@ -1,11 +0,0 @@ -.. -*- mode: rst -*- - -.. _client-tools-rpmng: - -===== -RPMng -===== - -Next-generation RPM tool, will be default in upcoming release. Handles -RPM sublties like epoch and prelinking and 64-bit platforms better than -RPM client tool. diff --git a/doc/client/tools/smf.txt b/doc/client/tools/smf.txt deleted file mode 100644 index 4829a14ed..000000000 --- a/doc/client/tools/smf.txt +++ /dev/null @@ -1,15 +0,0 @@ -.. -*- mode: rst -*- - -.. _client-tools-smf: - -=== -SMF -=== - -Solaris Service Support. - -Example legacy run service (lrc): - -.. code-block:: xml - - <BoundService name='/etc/rc2_d/S47pppd' FMRI='lrc:/etc/rc2_d/S47pppd' status='off' type='smf'/> diff --git a/doc/client/tools/sysv.txt b/doc/client/tools/sysv.txt deleted file mode 100644 index c08614c52..000000000 --- a/doc/client/tools/sysv.txt +++ /dev/null @@ -1,9 +0,0 @@ -.. -*- mode: rst -*- - -.. _client-tools-sysv: - -==== -SYSV -==== - -Handles System V Packaging format that is available on Solaris. diff --git a/doc/client/tools/upstart.txt b/doc/client/tools/upstart.txt deleted file mode 100644 index 60d0cf4ef..000000000 --- a/doc/client/tools/upstart.txt +++ /dev/null @@ -1,11 +0,0 @@ -.. -*- mode: rst -*- - -.. _client-tools-upstart: - -======= -Upstart -======= - -Upstart service support. Uses `Upstart`_ to configure services. - -.. _Upstart: http://upstart.ubuntu.com/ diff --git a/doc/client/tools/yum.txt b/doc/client/tools/yum.txt deleted file mode 100644 index fcb5244df..000000000 --- a/doc/client/tools/yum.txt +++ /dev/null @@ -1,11 +0,0 @@ -.. -*- mode: rst -*- - -.. _client-tools-yum: - -=== -Yum -=== - -.. warning:: Deprecated in favor of :ref:`YUMng <client-tools-yumng>` - -Handles RPMs using the YUM package manager. diff --git a/doc/conf.py b/doc/conf.py index e11cc4ca8..77ab6fd94 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -36,7 +36,8 @@ source_suffix = '.txt' #source_encoding = 'utf-8' # The master toctree document. -master_doc = 'contents' +#master_doc = 'contents' +master_doc = 'index' # General information about the project. project = u'Bcfg2' diff --git a/doc/contents.txt b/doc/contents.txt index df5c5350c..ab66e1b55 100644 --- a/doc/contents.txt +++ b/doc/contents.txt @@ -2,13 +2,12 @@ .. _contents: -========================================== -Welcome to Bcfg2's |version| documentation -========================================== +============================= +Bcfg2 documentation |release| +============================= .. toctree:: :maxdepth: 2 - :numbered: introduction/index installation/index @@ -18,7 +17,7 @@ Welcome to Bcfg2's |version| documentation client/index reports/index development/index - getting_help/index + help/index glossary appendix/index diff --git a/doc/development/client-driver.txt b/doc/development/client-driver.txt index 19da9cb67..cc065dd32 100644 --- a/doc/development/client-driver.txt +++ b/doc/development/client-driver.txt @@ -10,20 +10,20 @@ driver for a configuration element type. The included example describes an existing driver, and the process that was used to create it. #. Pick a name for the driver. In this case, we picked the name RPM. -#. Add "RPM" to the ``__all__ list`` in ``src/lib/Client/Tools/__init__.py`` +#. Add "RPM" to the ``__all__`` list in ``src/lib/Client/Tools/__init__.py`` #. Create a file in ``src/lib/Client/Tools`` with the same name (RPM.py) -#. Create a class in this file with the same name (``class RPM``) +#. Create a class in this file with the same name (class RPM) - * If it handles ``Package`` entries, subclass ``Bcfg2.Client.Tools.PkgTool`` + * If it handles **Package** entries, subclass ``Bcfg2.Client.Tools.PkgTool`` (from here referenced as branch [P]) - * If it handles ``Service`` entries, subclass ``Bcfg2.Client.Tools.SvcTool`` + * If it handles **Service** entries, subclass ``Bcfg2.Client.Tools.SvcTool`` (from here referenced as branch [S]) - * Otherwise, ``subclass Bcfg2.Client.Tools.Tool`` (from here referenced + * Otherwise, subclass ``Bcfg2.Client.Tools.Tool`` (from here referenced as branch [T]) #. Set ``__name__`` to "RPM" #. Add any required executable programs to ``__execs__`` -#. Set ``__handles__`` to a list of (``entry.tag``, ``entry.get('type')``) +#. Set ``__handles__`` to a list of (**entry.tag**, **entry.get('type')**) tuples. This determines which entries the Tool module can be used on. In this case, we set ``__handles__ = [('Package', 'rpm')]``. #. Add verification. This method should return True/False depending @@ -46,9 +46,9 @@ an existing driver, and the process that was used to create it. all-at-once installations, followed, in the case of failures, by single installations. To enable this support, set the pkgtype attribute to the package type handled by this driver. Set the - ``pkgtool`` to a tuple ("command string %s", ("per-package string + pkgtool to a tuple ("command string %s", ("per-package string format", [list of package entry fields])). For RPM, we have - ``setup pkgtool = ("rpm --oldpackage --replacepkgs --quiet -U %s", ("%s", ["url"]))`` + setup ``pkgtool = ("rpm --oldpackage --replacepkgs --quiet -U %s", ("%s", ["url"]))`` #. Implement entry removal diff --git a/doc/development/documentation.txt b/doc/development/documentation.txt index 8223670b8..0f75b9bba 100644 --- a/doc/development/documentation.txt +++ b/doc/development/documentation.txt @@ -19,22 +19,23 @@ The wiki .. _MCS: http://www.mcs.anl.gov/ .. _Argonne National Laboratory: http://www.anl.gov/ -A python-based Trac_ instance is used for the Bcfg2 website. The -Wiki_ part of the website can be edited after you have successful -logged in. For the login is a vaild OpenID provider needed and an -interaction from an administrator. Please request your access to -the Wiki_ on the :ref:`mailinglist` or in the :ref:`ircchannel`. +A python-based Trac_ instance is used for the Bcfg2 development +website. The Wiki_ part of the website can be edited after you +have successfully logged in. In order to login, a vaild OpenID +provider is needed. Please request your access to the Wiki_ on the +:ref:`help-mailinglist` or in the :ref:`help-irc`. The manual ---------- .. _rst: http://en.wikipedia.org/wiki/ReStructuredText .. _Sphinx: http://sphinx.pocoo.org -.. _Docutils: +.. _Docutils: -The source for the manual is located in the `doc/` directory in the -SVN repository or in the source tarball. All files are written in -rst_ (ReStructuredText). For the build process we are using Sphinx_. +The source for the manual is located in the ``doc/`` directory in the +git repository or in the source tarball. All files are written in +rst_ (ReStructuredText) format. Sphinx_ is used to build the +documentation from the restructured text sources. Building the Manual ^^^^^^^^^^^^^^^^^^^ @@ -42,7 +43,7 @@ Building the Manual * Install the prerequisites. Docutils_ and Sphinx_ are needed to build. * For Debian (Lenny) the tools are available in the `backports <http://www.backports.org/dokuwiki/doku.php?id=instructionst>`_ repository; installation can be done with the following:: - + apt-get -t lenny-backports install python-sphinx * The needed tools for Fedora based systems are in the `Fedora Package Collection <https://admin.fedoraproject.org/pkgdb>`_; installation can be done easily with Yum:: @@ -56,20 +57,14 @@ Building the Manual * Download the source. Please refer to :ref:`source` for more details. -* Building the HTML version, run the following command in the `doc/` directory. The output will appear in `../build/sphinx/html`:: +* Build the HTML version by running the following command in the + top level of the source directory. The output will appear in + ``build/sphinx/html``:: python setup.py build_sphinx * Building the PDF version :: - - python setup.py build_sphinx --builder=latex + + python setup.py build_sphinx --builder=latex cd build/sphinx/latex make - -The latest version of the manual -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The latest version of the manual can always be found -`on the Four Kitchens server <http://doc.bcfg2.fourkitchens.com/>`_. - -This is an auto-updated from the `Launchpad mirror <https://code.launchpad.net/~vcs-imports/bcfg2/trunk>`_. diff --git a/doc/development/index.txt b/doc/development/index.txt index 222978c98..352000dc8 100644 --- a/doc/development/index.txt +++ b/doc/development/index.txt @@ -6,19 +6,12 @@ Bcfg2 Development ================= -There are several ways users can contribute to the Bcfg2 project. +There are many ways to get involved in Bcfg2 development. Here we will +outline some things that can help you get familiar with the various +areas of the Bcfg2 code. -* Developing code -* Testing prereleases -* Reporting bugs -* Adding to the common repository -* Improving the wiki and writing documentation - -This section will outline some things that can help you get familiar -with the various areas of the Bcfg2 code. - -Send patches to the :ref:`mailinglist` or create a trac +Send patches to the :ref:`help-mailinglist` or create a trac `ticket <https://trac.mcs.anl.gov/projects/bcfg2/newticket>`_ 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 @@ -33,22 +26,16 @@ The source tree can be checked out by running:: git clone git://git.mcs.anl.gov/bcfg2.git Users wishing to contribute on a regular basis can apply for direct -git access. Mail the :ref:`mailinglist` for details. +git access. Mail the :ref:`help-mailinglist` for details. .. toctree:: :maxdepth: 1 - + tips setup client-driver plugins - writing_plugins - plugin-types - writing_specification - server testing documentation docstyleguide - emacs_snippet - vim_snippet diff --git a/doc/development/plugin-types.txt b/doc/development/plugin-types.txt deleted file mode 100644 index 5f0a4771a..000000000 --- a/doc/development/plugin-types.txt +++ /dev/null @@ -1,46 +0,0 @@ -.. -*- mode: rst -*- - -.. _development-plugin-types: - -Server Plugin Types -------------------- - -Generator -^^^^^^^^^ - -Generator plugins contribute to literal client configurations - -Structure -^^^^^^^^^ - -Structure Plugins contribute to abstract client configurations - -Metadata -^^^^^^^^ - -Signal metadata capabilities - -Connector -^^^^^^^^^ - -Connector Plugins augment client metadata instances - -Probing -^^^^^^^ - -Signal probe capability - -Statistics -^^^^^^^^^^ - -Signal statistics handling capability - -Decision -^^^^^^^^ - -Signal decision handling capability - -Version -^^^^^^^ - -Interact with various version control systems diff --git a/doc/development/plugins.txt b/doc/development/plugins.txt index b6debba24..709b9fcec 100644 --- a/doc/development/plugins.txt +++ b/doc/development/plugins.txt @@ -3,7 +3,7 @@ .. _development-plugins: Bcfg2 Plugin development ------------------------- +======================== While the Bcfg2 server provides a good interface for representing general system configurations, its plugin interface offers the ability @@ -12,7 +12,7 @@ problems encountered by a particular site. This chapter describes what plugins are good for, what they can do, and how to implement them. Bcfg2 Plugins -^^^^^^^^^^^^^ +------------- Bcfg2 plugins are loadable python modules that the Bcfg2 server loads at initialization time. These plugins can contribute to the functions already @@ -43,3 +43,171 @@ The following table describes the various functions of bcfg2 plugins. | | expose internal functions. | +--------------------+---------------------------------------------+ +Server Plugin Types +------------------- + +Generator +^^^^^^^^^ + +Generator plugins contribute to literal client configurations + +Structure +^^^^^^^^^ + +Structure Plugins contribute to abstract client configurations + +Metadata +^^^^^^^^ + +Signal metadata capabilities + +Connector +^^^^^^^^^ + +Connector Plugins augment client metadata instances + +Probing +^^^^^^^ + +Signal probe capability + +Statistics +^^^^^^^^^^ + +Signal statistics handling capability + +Decision +^^^^^^^^ + +Signal decision handling capability + +Version +^^^^^^^ + +Interact with various version control systems + +Writing Bcfg2 Server Plugins +---------------------------- + +Bcfg2 plugins are python classes that subclass from +Bcfg2.Server.Plugin.Plugin. Several plugin-specific values must be set +in the new plugin. These values dictate how the new plugin will behave +with respect to the above four functions. The following table describes +all important member fields. + ++-----------------+-----------------------------------+--------------------------+ +| Name | Description | Format | ++=================+===================================+==========================+ +| __name__ | The name of the plugin | string | ++-----------------+-----------------------------------+--------------------------+ +| __version__ | The plugin version (generally | string | +| | tied to revctl keyword expansion) | | ++-----------------+-----------------------------------+--------------------------+ +| __author__ | The plugin author. | string | ++-----------------+-----------------------------------+--------------------------+ +| __author__ | The plugin author. | string | ++-----------------+-----------------------------------+--------------------------+ +| __rmi__ | Set of functions to be exposed as | List of function names | +| | XML-RPC functions | (strings) | ++-----------------+-----------------------------------+--------------------------+ +| Entries | Multidimentional dictionary of | Dictionary of | +| | keys that point to the function | ConfigurationEntityType, | +| | used to bind literal contents for | Name keys, and function | +| | a given configuration entity. | reference values | ++-----------------+-----------------------------------+--------------------------+ +| BuildStructures | Function that returns a list of | Member function | +| | the structures for a given client | | ++-----------------+-----------------------------------+--------------------------+ +| GetProbes | Function that returns a list of | Member function | +| | probes that a given client should | | +| | execute | | ++-----------------+-----------------------------------+--------------------------+ +| ReceiveData | Function that accepts the probe | Member function | +| | results for a given client. | | ++-----------------+-----------------------------------+--------------------------+ + +Example Plugin +^^^^^^^^^^^^^^ + +.. code-block:: python + + import Bcfg2.Server.Plugin + class MyPlugin(Bcfg2.Server.Plugin.Plugin): + '''An example plugin''' + # All plugins need to subclass Bcfg2.Server.Plugin.Plugin + __name__ = 'MyPlugin' + __version__ = '1' + __author__ = 'me@me.com' + __rmi__ = ['myfunction'] + # myfunction is not available remotely as MyPlugin.myfunction + + def __init__(self, core, datastore): + Bcfg2.Server.Plugin.Plugin.__init__(self, core, datastore) + self.Entries = {'Path':{'/etc/foo.conf': self.buildFoo}} + + def myfunction(self): + '''function for xmlrpc rmi call''' + #do something + return True + + def buildFoo(self, entry, metadata): + '''Bind per-client information into entry based on metadata''' + entry.attrib.update({'type':'file', 'owner':'root', 'group':'root', 'perms':'644'}) + entry.text = '''contents of foo.conf''' + +Example Connector +^^^^^^^^^^^^^^^^^ + +.. code-block:: python + + import Bcfg2.Server.Plugin + + class Foo(Bcfg2.Server.Plugin.Plugin, + Bcfg2.Server.Plugin.Connector): + '''The Foo plugin is here to illustrate a barebones connector''' + name = 'Foo' + version = '$Revision: $' + experimental = True + + def __init__(self, core, datastore): + Bcfg2.Server.Plugin.Plugin.__init__(self, core, datastore) + Bcfg2.Server.Plugin.Connector.__init__(self) + self.store = XMLFileBacked(self.data, core.fam) + + def get_additional_data(self, metadata): + + mydata = {} + for data in self.store.entries['foo.xml'].data.get("foo", []): + + mydata[data] = "bar" + + return dict([('mydata', mydata)]) + + def get_additional_groups(self, meta): + return self.cgroups.get(meta.hostname, list()) + +Example Metadata plugin +^^^^^^^^^^^^^^^^^^^^^^^ + +If you would like to define your own Metadata plugin (to extend/change +functionality of the existing Metadata plugin), here are the steps to +do so. We will call our new plugin `MyMetadata`. + +#. Add MyMetadata.py + + .. code-block:: python + + __revision__ = '$Revision$' + + import Bcfg2.Server.Plugins.Metadata + + class MyMetadata(Bcfg2.Server.Plugins.Metadata.Metadata): + '''This class contains data for bcfg2 server metadata''' + __version__ = '$Id$' + __author__ = 'bcfg-dev@mcs.anl.gov' + + def __init__(self, core, datastore, watch_clients=True): + Bcfg2.Server.Plugins.Metadata.Metadata.__init__(self, core, datastore, watch_clients) + +#. Add MyMetadata to ``src/lib/Server/Plugins/__init__.py`` +#. Replace Metadata with MyMetadata in the plugins line of bcfg2.conf diff --git a/doc/development/server.txt b/doc/development/server.txt deleted file mode 100644 index 0f594422e..000000000 --- a/doc/development/server.txt +++ /dev/null @@ -1,83 +0,0 @@ -.. -*- mode: rst -*- - -.. _development-server-plugins: - -Writing Server Plugins ----------------------- - -Metadata -^^^^^^^^ - -If you would like to define your own Metadata plugin (to extend/change -functionality of the existing Metadata plugin), here are the steps to -do so. We will call our new plugin `MyMetadata`. - -#. Add MyMetadata.py - - .. code-block:: python - - __revision__ = '$Revision$' - - import Bcfg2.Server.Plugins.Metadata - - class MyMetadata(Bcfg2.Server.Plugins.Metadata.Metadata): - '''This class contains data for bcfg2 server metadata''' - __version__ = '$Id$' - __author__ = 'bcfg-dev@mcs.anl.gov' - - def __init__(self, core, datastore, watch_clients=True): - Bcfg2.Server.Plugins.Metadata.Metadata.__init__(self, core, datastore, watch_clients) - -#. Add MyMetadata to ``src/lib/Server/Plugins/__init__.py`` -#. Replace Metadata with MyMetadata in the plugins line of bcfg2.conf - -.. _development-server-packages: - -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. - -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. - -The APT source in ``src/lib/Server/Plugins/Packages.py`` provides a -relatively simple implementation of a source. diff --git a/doc/development/setup.txt b/doc/development/setup.txt index 08a85dac1..8729ee76e 100644 --- a/doc/development/setup.txt +++ b/doc/development/setup.txt @@ -8,7 +8,7 @@ Environment setup for development * Check out a copy of the code:: - svn co https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2 + git clone git://git.mcs.anl.gov/bcfg2.git * Create link to ``src/lib``:: diff --git a/doc/development/writing_plugins.txt b/doc/development/writing_plugins.txt deleted file mode 100644 index 40e077e43..000000000 --- a/doc/development/writing_plugins.txt +++ /dev/null @@ -1,104 +0,0 @@ -.. -*- mode: rst -*- - -.. _development-write-plugins: - -Writing Bcfg2 Plugins -===================== - -Bcfg2 plugins are python classes that subclass from -Bcfg2.Server.Plugin.Plugin. Several plugin-specific values must be set -in the new plugin. These values dictate how the new plugin will behave -with respect to the above four functions. The following table describes -all important member fields. - -+-----------------+-----------------------------------+--------------------------+ -| Name | Description | Format | -+=================+===================================+==========================+ -| __name__ | The name of the plugin | string | -+-----------------+-----------------------------------+--------------------------+ -| __version__ | The plugin version (generally | string | -| | tied to revctl keyword expansion) | | -+-----------------+-----------------------------------+--------------------------+ -| __author__ | The plugin author. | string | -+-----------------+-----------------------------------+--------------------------+ -| __author__ | The plugin author. | string | -+-----------------+-----------------------------------+--------------------------+ -| __rmi__ | Set of functions to be exposed as | List of function names | -| | XML-RPC functions | (strings) | -+-----------------+-----------------------------------+--------------------------+ -| Entries | Multidimentional dictionary of | Dictionary of | -| | keys that point to the function | ConfigurationEntityType, | -| | used to bind literal contents for | Name keys, and function | -| | a given configuration entity. | reference values | -+-----------------+-----------------------------------+--------------------------+ -| BuildStructures | Function that returns a list of | Member function | -| | the structures for a given client | | -+-----------------+-----------------------------------+--------------------------+ -| GetProbes | Function that returns a list of | Member function | -| | probes that a given client should | | -| | execute | | -+-----------------+-----------------------------------+--------------------------+ -| ReceiveData | Function that accepts the probe | Member function | -| | results for a given client. | | -+-----------------+-----------------------------------+--------------------------+ - -Example Plugin --------------- - -.. code-block:: python - - import Bcfg2.Server.Plugin - class MyPlugin(Bcfg2.Server.Plugin.Plugin): - '''An example plugin''' - # All plugins need to subclass Bcfg2.Server.Plugin.Plugin - __name__ = 'MyPlugin' - __version__ = '1' - __author__ = 'me@me.com' - __rmi__ = ['myfunction'] - # myfunction is not available remotely as MyPlugin.myfunction - - def __init__(self, core, datastore): - Bcfg2.Server.Plugin.Plugin.__init__(self, core, datastore) - self.Entries = {'Path':{'/etc/foo.conf': self.buildFoo}} - - def myfunction(self): - '''function for xmlrpc rmi call''' - #do something - return True - - def buildFoo(self, entry, metadata): - '''Bind per-client information into entry based on metadata''' - entry.attrib.update({'type':'file', 'owner':'root', 'group':'root', 'perms':'644'}) - entry.text = '''contents of foo.conf''' - -Example Connector ------------------ - -.. code-block:: python - - import Bcfg2.Server.Plugin - - class Foo(Bcfg2.Server.Plugin.Plugin, - Bcfg2.Server.Plugin.Connector): - '''The Foo plugin is here to illustrate a barebones connector''' - name = 'Foo' - version = '$Revision: $' - experimental = True - - def __init__(self, core, datastore): - Bcfg2.Server.Plugin.Plugin.__init__(self, core, datastore) - Bcfg2.Server.Plugin.Connector.__init__(self) - self.store = XMLFileBacked(self.data, core.fam) - - def get_additional_data(self, metadata): - - mydata = {} - for data in self.store.entries['foo.xml'].data.get("foo", []): - - mydata[data] = "bar" - - return dict([('mydata', mydata)]) - - def get_additional_groups(self, meta): - return self.cgroups.get(meta.hostname, list()) - diff --git a/doc/development/writing_specification.txt b/doc/development/writing_specification.txt deleted file mode 100644 index 4e1c03483..000000000 --- a/doc/development/writing_specification.txt +++ /dev/null @@ -1,54 +0,0 @@ -.. -*- mode: rst -*- - -.. _development-writing_specification: - -=========================== -Writing Bcfg2 Specification -=========================== - -Bcfg2 specifications are logically divided in to three areas: - -* Metadata -* Abstract -* Literal - -The metadata portion of the configuration assigns a client to its profile -group and to its non-profile groups. The profile group is assigned -in ``Metadata/clients.xml`` and the non profile group assignments are in -``Metadata/groups.xml``. - -The group memberships contained in the metadata are then used to constuct -an abstract configuration for the client. An abstract configuration for -a client identifies the configuration entities (packages, configuration -files, service, etc) that a client requires, but it does not identify -them explicitly. For instance an abstract configuration may identify -that a client needs the Bcfg2 package with - -.. code-block:: xml - - <Package name=bcfg2/> - -but this does not explicitly identify that an RPM package version -0.9.2 should be loaded from http://rpm.repo.server/bcfg2-1.0.1-0.1.rpm. -The abstract configuration is defined in the xml configuration files -for the Base and Bundles plugins. - -A combination of a clients metadata (group memberships) and abstract -configuration is then used to generate the clients literal configuration. -For instance the above abstract configuration entry may generate a -literal configuration of - - -.. code-block:: xml - - <Package name='bcfg2' version='1.0.1-0.1' type='yum'/> - -A clients literal configuration is generated by a number of plugins that -handle the different configuration entities. - - -.. figure:: specification_overview.png - :width: 60% - :alt: Specification overview - :align: center - diff --git a/doc/getting_help/error-messages.txt b/doc/getting_help/error-messages.txt deleted file mode 100644 index 72d1f1f40..000000000 --- a/doc/getting_help/error-messages.txt +++ /dev/null @@ -1,45 +0,0 @@ -.. -*- mode: rst -*- - -.. _error-messages: - -============== -Error Messages -============== - -This page describes error messages produced by Bcfg2 and steps that -can be taken to remedy them. - -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| Error | Location | Meaning | Repair | -+===========================================================================+==========+=====================================================================================================+=========+ -| Incomplete information for entry <EntryTag>:<EntryName>; cannot verify | Client | The described entry is not fully specified by the server, so no verification can be performed. | [#f1]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| Incomplete information for entry <EntryTag>:<EntryName>; cannot install | Client | The described entry is not fully specified by the server, so no verification can be performed. | [#f2]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| The following entries are not handled by any tool: <EntryTag>:<EntryName> | Client | The client cannot figure out how to handle this entry. | [#f3]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| no server x509 fingerprint; no server verification performed! | Client | The client is unable to verify the server | [#f4]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| Failed to bind entry: <EntryTag> <EntryName> | Server | The server was unable to find a suitable version of entry for client. | [#f5]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| Failed to bind to socket | Server | The server was unable to bind to the tcp server socket. | [#f6]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| Failed to load ssl key <path> | Server | The server was unable to read and process the ssl key. | [#f7]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| Failed to read file <path> | Server | The server failed to read the specified file | [#f8]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| Failed to parse file <path> | Server | The server failed to parse the specified XML file | [#f9]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ -| Client metadata resolution error for <IP> | Server | The server cannot resolve the client hostname or the client is associated with a non-profile group. | [#f10]_ | -+---------------------------------------------------------------------------+----------+-----------------------------------------------------------------------------------------------------+---------+ - -.. [#f1] This entry is not being bound. Ensure that a version of this entry applies to this client. -.. [#f2] This entry is not being bound. Ensure that a version of this entry applies to this client. -.. [#f3] Add a type to the generator definition for this entry -.. [#f4] Run bcfg2-admin fingerprint on the server and add it to the client bcfg2.conf as mentioned here -.. [#f5] This entry is not being bound. Ensure that a version of this entry applies to this client. -.. [#f6] Ensure that another instance of the daemon (or any other process) is not listening on the same port. -.. [#f7] Ensure that the key is readable by the user running the daemon and that it is well-formed. -.. [#f8] Ensure that this file still exists; a frequent cause is the deletion of a temp file. -.. [#f9] Ensure that the file is properly formed XML. -.. [#f10] Fix hostname resolution for the client or ensure that the profile group is properly setup. diff --git a/doc/getting_help/index.txt b/doc/getting_help/index.txt deleted file mode 100644 index 1060a8f4b..000000000 --- a/doc/getting_help/index.txt +++ /dev/null @@ -1,41 +0,0 @@ -.. -*- mode: rst -*- - -.. _gettinghelp-index: - -.. _IRC logs: http://colabti.org/irclogger/irclogger_logs/bcfg2 - - -Getting Help -============ - -Having trouble? We'd like to help! - -There are several ways to get in touch with the community around Bcfg2. - -* Try the :ref:`FAQ <faq-index>` -- it's got answers to many common - questions. - -* Looking for specific information? Try the :ref:`genindex`, - :ref:`modindex`, or the :ref:`detailed table of contents <contents>`. - -* Search for information in the :ref:`mailinglist`. - -* Ask a question in the :ref:`ircchannel`, or search the `IRC logs`_ - to see if its been asked before. - -Note that the IRC channel tends to be much busier than the mailing -list; use whichever seems most appropriate for your query, but don't -let the lack of mailing list activity make you think the project isn't -active. - - -.. toctree:: - :maxdepth: 1 - - reporting - mailinglist - ircchannel - faq/index - error-messages - manpages - troubleshooting diff --git a/doc/getting_help/manpages.txt b/doc/getting_help/manpages.txt deleted file mode 100644 index 14c22a92e..000000000 --- a/doc/getting_help/manpages.txt +++ /dev/null @@ -1,16 +0,0 @@ -.. -*- mode: rst -*- - -.. _manpages: - -============ -Manual pages -============ - -These are copies of the bcfg2 manual pages created with man2html. -The most recent versions of these man pages are always in the `man/` -directory in the source. - -.. toctree:: - :glob: - - manpages/* diff --git a/doc/getting_help/manpages/bcfg2-admin.txt b/doc/getting_help/manpages/bcfg2-admin.txt deleted file mode 100644 index 4440c7134..000000000 --- a/doc/getting_help/manpages/bcfg2-admin.txt +++ /dev/null @@ -1,11 +0,0 @@ -.. -*- mode: rst -*- - -.. _manpages-bcfg2-admin: - -=========== -bcfg2-admin -=========== - -The man page of ``bcfg2-admin``. :: - - man bcfg2-admin diff --git a/doc/getting_help/manpages/bcfg2-build-reports.txt b/doc/getting_help/manpages/bcfg2-build-reports.txt deleted file mode 100644 index 217c25627..000000000 --- a/doc/getting_help/manpages/bcfg2-build-reports.txt +++ /dev/null @@ -1,11 +0,0 @@ -.. -*- mode: rst -*- - -.. _manpages-bcfg2-build-reports: - -=================== -bcfg2-build-reports -=================== - -The man page of ``bcfg2-build-reports``. :: - - man bcfg2-build-reports diff --git a/doc/getting_help/manpages/bcfg2-conf.txt b/doc/getting_help/manpages/bcfg2-conf.txt deleted file mode 100644 index 623521a67..000000000 --- a/doc/getting_help/manpages/bcfg2-conf.txt +++ /dev/null @@ -1,11 +0,0 @@ -.. -*- mode: rst -*- - -.. _manpages-bcfg2.conf: - -========== -bcfg2.conf -========== - -The man page of ``bcfg2.conf``. :: - - man bcfg2.conf diff --git a/doc/getting_help/manpages/bcfg2-info.txt b/doc/getting_help/manpages/bcfg2-info.txt deleted file mode 100644 index 751905e0b..000000000 --- a/doc/getting_help/manpages/bcfg2-info.txt +++ /dev/null @@ -1,11 +0,0 @@ -.. -*- mode: rst -*- - -.. _manpages-bcfg2-info: - -========== -bcfg2-info -========== - -The man page of ``bcfg2-info``. :: - - man bcfg2-info diff --git a/doc/getting_help/manpages/bcfg2-repo-validate.txt b/doc/getting_help/manpages/bcfg2-repo-validate.txt deleted file mode 100644 index b13bd928b..000000000 --- a/doc/getting_help/manpages/bcfg2-repo-validate.txt +++ /dev/null @@ -1,11 +0,0 @@ -.. -*- mode: rst -*- - -.. _manpages-bcfg2-repo-validate: - -=================== -bcfg2-repo-validate -=================== - -The man page of ``bcfg2-repo-validate``. :: - - man bcfg2-repo-validate diff --git a/doc/getting_help/manpages/bcfg2-server.txt b/doc/getting_help/manpages/bcfg2-server.txt deleted file mode 100644 index 27002789e..000000000 --- a/doc/getting_help/manpages/bcfg2-server.txt +++ /dev/null @@ -1,11 +0,0 @@ -.. -*- mode: rst -*- - -.. _manpages-bcfg2-server: - -============ -bcfg2-server -============ - -The man page of ``bcfg2-server``. :: - - man bcfg2-server diff --git a/doc/getting_help/manpages/bcfg2.txt b/doc/getting_help/manpages/bcfg2.txt deleted file mode 100644 index 4e93ab449..000000000 --- a/doc/getting_help/manpages/bcfg2.txt +++ /dev/null @@ -1,11 +0,0 @@ -.. -*- mode: rst -*- - -.. _manpages-bcfg2: - -===== -bcfg2 -===== - -The man page of bcfg2. :: - - man bcfg2 diff --git a/doc/getting_help/reporting.txt b/doc/getting_help/reporting.txt deleted file mode 100644 index cd53b1206..000000000 --- a/doc/getting_help/reporting.txt +++ /dev/null @@ -1,12 +0,0 @@ -.. -*- mode: rst -*- - -.. _reporting: - -.. _tracker: http://trac.mcs.anl.gov/projects/bcfg2/wiki - -============== -Reporting bugs -============== - -Report bugs with Bcfg2 in our `tracker`_. - diff --git a/doc/getting_started/index.txt b/doc/getting_started/index.txt index 786c70290..9661fcb89 100644 --- a/doc/getting_started/index.txt +++ b/doc/getting_started/index.txt @@ -6,10 +6,13 @@ Getting started =============== -The steps below should get you from just thinking about a -configuration management system to an operational installation of -Bcfg2. If you get stuck, be sure to check the :ref:`mailinglist` -or to drop in on our :ref:`ircchannel`. +The steps below should get you from just thinking about a configuration +management system to an operational installation of Bcfg2. If you get +stuck, be sure to check the :ref:`help-mailinglist` or to drop in on +our :ref:`help-irc`. + +See the `Platform-specific Quickstart Notes`_ at the end of this page +if you happen to be using one of the more common operating systems. Get and Install Bcfg2 Server ============================ @@ -18,7 +21,7 @@ We recommend running the server on a Linux machine for ease of deployment due to the availability of packages for the dependencies. First, you need to download and install Bcfg2. The section -:ref:`installation-index` in this manual describes the steps to take. +:ref:`installation-index` in this manual describes the steps to take. To start, you will need to install the server on one machine and the client on one or more machines. Yes, your server can also be a client (and should be by the time your environment is fully managed). @@ -50,26 +53,25 @@ acting like it is your first client. .. note:: - The following command will tell the client to run in no-op mode, - meaning it will only check the client against the repository and - report any changes it sees. It won't make any changes (partially - because you haven't populated the repository with any - yet). However, nobody is perfect - you can make a typo, our - software can have bugs, monkeys can break in and hit enter before - you are done. Don't run this command on a production system if you - don't know what it does and aren't prepared for the - consequences. We don't know of anybody having problems with it - before, but it is better to be safe than sorry. + The following command will tell the client to run in no-op mode, + meaning it will only check the client against the repository and + report any differences it sees. It won't make any changes (partially + because you haven't populated the repository with any yet). However, + nobody is perfect. You can make a typo, our software can have bugs, + monkeys can break in and hit enter before you are done. Don't run + this command on a production system if you don't know what it does + and aren't prepared for the consequences. We don't know of anybody + having problems with it before, but it is better to be safe than sorry. And now for the command:: - bcfg2 -q -v -n + bcfg2 -q -v -n That can be translated as "bcfg2 quick verbose no-op". The output should be something similar to:: Loaded tool drivers: - Chkconfig POSIX PostInstall RPM + Chkconfig POSIX YUMng Phase: initial Correct entries: 0 @@ -87,9 +89,10 @@ should be something similar to:: Perfect! We have started out with an empty configuration, and none of our configuration elements are correct. It doesn't get much cleaner than that. But what about those unmanaged entries? Those are the extra -configuration elements (probably all packages at the moment) that -still aren't managed. Your goal now is to migrate each of those plus -any it can't see up to the "Correct entries" line. +configuration elements (probably all packages and services at the +moment) that still aren't managed, but have been detected by the client +tools. Your goal now is to migrate each of those plus any it can't see +up to the "Correct entries" line. Populate Repository =================== @@ -105,7 +108,7 @@ After the above steps, you should have a toplevel repository structure that looks like:: bcfg-server:~ # ls /var/lib/bcfg2 - Bundler/ Cfg/ Metadata/ Pkgmgr/ Rules/ SSHbase/ etc/ + Base/ Bundler/ Cfg/ Metadata/ Pkgmgr/ Rules/ SSHbase/ etc/ The place to start is the Metadata directory, which contains two files: ``clients.xml`` and ``groups.xml``. Your current @@ -113,9 +116,9 @@ files: ``clients.xml`` and ``groups.xml``. Your current .. code-block:: xml - <Clients version="3.0"> - <Client profile="basic" pingable="Y" pingtime="0" name="bcfg-server.example.com"/> - </Clients> + <Clients version="3.0"> + <Client profile="basic" pingable="Y" pingtime="0" name="bcfg-server.example.com"/> + </Clients> The ``clients.xml`` file is just a series of ``<Client />`` tags, each of which describe one host you manage. Right now we only manage one @@ -130,27 +133,26 @@ Our simple ``groups.xml`` file looks like: .. code-block:: xml - <Groups version='3.0'> - <Group profile='true' public='false' name='basic'> - <Group name='suse'/> - </Group> - <Group name='ubuntu' toolset='debian'/> - <Group name='debian' toolset='debian'/> - <Group name='redhat' toolset='rh'/> - <Group name='suse' toolset='rh'/> - <Group name='mandrake' toolset='rh'/> - <Group name='solaris' toolset='solaris'/> - </Groups> - -There are two types of groups in Bcfg: profile groups -(``profile='true'``) and non-profile groups -(``profile='false'``). Profile groups can act as top-level groups to -which clients can bind, while non-profile groups only exist as members -of other groups. In our simple starter case, we have a profile group -named ``basic``, and that is the group that our first client bound -to. Our first client is a SuSE machine, so it contains the ``suse`` -group. Of course, ``bcfg2-admin`` isn't smart enough to fill out the -rest of your config, so the ``suse`` group further down is empty. + <Groups version='3.0'> + <Group profile='true' public='false' name='basic'> + <Group name='suse'/> + </Group> + <Group name='ubuntu' /> + <Group name='debian' /> + <Group name='redhat' /> + <Group name='suse' /> + <Group name='mandrake' /> + <Group name='solaris' /> + </Groups> + +There are two types of groups in Bcfg: profile groups (``profile='true'``) +and non-profile groups (``profile='false'``). Profile groups can act as +top-level groups to which clients can bind, while non-profile groups only +exist as members of other groups. In our simple starter case, we have +a profile group named ``basic``, and that is the group that our first +client bound to. Our first client is a SuSE machine, so it contains the +``suse`` group. Of course, ``bcfg2-admin`` isn't smart enough to fill +out the rest of your config, so the ``suse`` group further down is empty. Let's say the first thing we want to set up on our machine is the message of the day. To do this, we simply need to create a Bundle and @@ -159,7 +161,7 @@ start out by adding .. code-block:: xml - <Bundle name='motd'/> + <Bundle name='motd'/> to the ``basic`` group. @@ -167,14 +169,14 @@ Next, we create a motd.xml file in the Bundler directory: .. code-block:: xml - <Bundle name='motd' version='2.0'> - <Path name='/etc/motd' /> - </Bundle> + <Bundle name='motd' version='2.0'> + <Path name='/etc/motd' /> + </Bundle> Now when we run the client, we get slightly different output:: Loaded tool drivers: - Chkconfig POSIX PostInstall RPM + Chkconfig POSIX YUMng Incomplete information for entry Path:/etc/motd; cannot verify Phase: initial @@ -225,16 +227,16 @@ Done! Now we just have 242 (or more) entries to take care of! directory to populate. You can find many samples of Bundles in the `Bundle Repository`_, many of which can be used without editing. -.. _Bundle Repository: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Plugins/Bundler/examples +.. _Bundle Repository: http://docs.bcfg2.org/server/plugins/structures/bundler/index.html#other-examples Next Steps ========== Several other utilities can help from this point on: -``bcfg2-info`` is a utility that instantiates a copy of the Bcfg2 server -core (minus the networking code) for examination. From this, you can -directly query: +:ref:`bcfg2-info <appendix-guides-using_bcfg2_info>` is a utility that +instantiates a copy of the bcfg2 server core (minus the networking code) +for examination. From this, you can directly query: * Client Metadata * Which entries are provided by particular plugins @@ -244,3 +246,9 @@ Run ``bcfg2-info``, and type help and the prompt when it comes up. ``bcfg2-admin`` can perform a variety of repository maintenance tasks. Run ``bcfg2-admin`` help for details. + +Platform-specific Quickstart Notes +================================== + +* :ref:`appendix-guides-centos` +* :ref:`appendix-guides-ubuntu` diff --git a/doc/getting_help/faq/client.txt b/doc/help/faq/client.txt index a230a84bb..8eb04e620 100644 --- a/doc/getting_help/faq/client.txt +++ b/doc/help/faq/client.txt @@ -10,7 +10,7 @@ FAQ: Client This means that the client does not have a copy of the CA for the server, so it can't verify that it is talking to the right server. To fix this issue, copy ``/etc/bcfg2.crt`` from the server to ``/etc/bcfg2.ca`` -on the client. Then add the following on the client. :: +on the client. Then add the following on the client.:: [communication] ca = /etc/bcfg2.ca diff --git a/doc/getting_help/faq/general.txt b/doc/help/faq/general.txt index f08bfb7b2..0534e72d2 100644 --- a/doc/getting_help/faq/general.txt +++ b/doc/help/faq/general.txt @@ -39,26 +39,10 @@ see why. **Why am I getting a traceback?** -If you get a traceback, please let us know. You can file a -`ticket <https://trac.mcs.anl.gov/projects/bcfg2/newticket>`_, send -the traceback to the :ref:`mailinglist`, or hop on -:ref:`ircchannel` and let us know. - -**What is the most common cause of "The following entries are not handled by any tool"?** - -Often it corresponds to entries that aren't bound by the server (for which you'll get error messages on the server). You should try inspecting the logs on the server to see what may be the cause. - -**How can I figure out if error is client or server side?** - -* Cache a copy of the client using ``bcfg2 -c /tmp/config.xml`` -* Search for the entry of interest -* If it looks correct, then there is a client issue - -This file contains all aspects of client configuration. It is structured as a series of bundles and base entries. - -.. note:: - - Most often the entry is not correct and the issue lies in the specification. +If you get a traceback, please let us know. You can file a `ticket +<https://trac.mcs.anl.gov/projects/bcfg2/newticket>`_, send the traceback +to the :ref:`help-mailinglist`, or hop on the :ref:`help-irc` and let +us know. **Where are the server log messages?** @@ -69,4 +53,4 @@ The bcfg2-server process logs to syslog facility LOG_DAEMON. The server produces Bcfg2 comes with XML schemas describing all of the XML formats used in the server repository. A validation command ``bcfg2-repo-validate`` is included with the source distribution and all packages. Run it with -the ``-v`` flag to see each file and the results if its validation. +the ``-v`` flag to see each file and the results if its validation. diff --git a/doc/getting_help/faq/index.txt b/doc/help/faq/index.txt index 27aa5303f..ee418d84d 100644 --- a/doc/getting_help/faq/index.txt +++ b/doc/help/faq/index.txt @@ -7,7 +7,7 @@ FAQ === The Frequently Asked Questions (FAQ) answers the most common questions -about Bcfg2. At the moment the FAQ is splitted into a general +about Bcfg2. At the moment the FAQ is splitted into a general and a client specfic section. .. toctree:: diff --git a/doc/help/index.txt b/doc/help/index.txt new file mode 100644 index 000000000..63c2ca350 --- /dev/null +++ b/doc/help/index.txt @@ -0,0 +1,42 @@ +.. -*- mode: rst -*- + +.. _help-index: + +======================= +Getting Help with Bcfg2 +======================= + +Having trouble? We'd like to help! + +There are several ways to get in touch with the Bcfg2 community. + +* Try the :ref:`FAQ <faq-index>` -- it's got answers to many common + questions. +* Check the :ref:`help-troubleshooting` page to see if you can narrow + down the cause of your issue. +* Looking for specific information? Try the :ref:`genindex`, + :ref:`modindex`, or the :ref:`detailed table of contents <contents>`. +* Search for information in the :ref:`help-mailinglist`. +* Visit our :ref:`help-irc`, or search the `IRC logs`_. + +Note that the IRC channel tends to be much busier than the mailing +list; use whichever seems most appropriate for your query, but don't +let the lack of mailing list activity make you think the project isn't +active. + +.. _IRC logs: http://colabti.org/irclogger/irclogger_logs/bcfg2 +.. _Bcfg2 mailing list archives: http://trac.mcs.anl.gov/projects/bcfg2/wiki/MailingList +.. _Trac ticket tracker: http://trac.mcs.anl.gov/projects/bcfg2/wiki + +Report A Bug +============ + +Report bugs with Bcfg2 on the `Trac ticket tracker`_. + +.. toctree:: + :hidden: + + mailinglist + irc + faq/index + troubleshooting diff --git a/doc/getting_help/ircchannel.txt b/doc/help/irc.txt index b97e5f6a6..303c39e68 100644 --- a/doc/getting_help/ircchannel.txt +++ b/doc/help/irc.txt @@ -3,13 +3,15 @@ .. _Freenode: http://chat.freenode.net .. _#bcfg2: irc://chat.freenode.net/bcfg2 -.. _ircchannel: +.. _help-irc: =========== IRC Channel =========== -The Bcfg2 IRC channel is `#bcfg2`_ on `Freenode`_. It is home to both support and development discussions. If you have a question, suggestion, or just want to know about Bcfg2, please drop in and say hi. +The Bcfg2 IRC channel is `#bcfg2`_ on `Freenode`_. It is home to both +support and development discussions. If you have a question, suggestion, +or just want to know about Bcfg2, please drop in and say hi. Archives are available at: http://colabti.org/irclogger/irclogger_logs/bcfg2 @@ -26,3 +28,18 @@ Archives are available at: http://colabti.org/irclogger/irclogger_logs/bcfg2 <label><input type=checkbox name=nick value="checked">Search in the nick field</label><br> <label><input type=checkbox name=text checked value="checked">Search in the text field</label><br> </form> + +Administrative Note +=================== + +If the IRC logging stops working for a while, coordinate on #bcfg2 and +then bug **feb** on #irclogger (freenode), and stick around on that +channel until you get an answer (**feb** is great, but busy and in a +non-US time zone). Actually as long as **ilogger2** is logged in you +should be okay (**feb** looks at the logs). + +If you have private logs for the period of time **ilogger2** was off the +channel, you can convert them to the will incorporate them into the online +logs. Be sure to strip out any private messages in your logs first :-) + +.. _format shown here: http://colabti.org/irclogger/irclogger_log/bcfg2?date=2008-03-21,Fri;raw=on diff --git a/doc/getting_help/mailinglist.txt b/doc/help/mailinglist.txt index c77caa0c4..c77caa0c4 100644 --- a/doc/getting_help/mailinglist.txt +++ b/doc/help/mailinglist.txt diff --git a/doc/getting_help/troubleshooting.txt b/doc/help/troubleshooting.txt index cce9c3d78..0892587aa 100644 --- a/doc/getting_help/troubleshooting.txt +++ b/doc/help/troubleshooting.txt @@ -1,6 +1,6 @@ .. -*- mode: rst -*- -.. _troubleshooting: +.. _help-troubleshooting: =============== Troubleshooting diff --git a/doc/index.txt b/doc/index.txt index 583ea38e3..98616ab72 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -2,9 +2,9 @@ .. _index: -========================================== -Welcome to Bcfg2's |version| documentation -========================================== +============================= +Bcfg2 documentation |release| +============================= What is Bcfg2? ============== @@ -38,7 +38,6 @@ Bcfg2 can enable the construction of complex change management and deployment strategies. .. toctree:: - :numbered: :maxdepth: 2 contents diff --git a/doc/installation/distributions.txt b/doc/installation/distributions.txt index 5a86e81d5..38b34f14d 100644 --- a/doc/installation/distributions.txt +++ b/doc/installation/distributions.txt @@ -3,15 +3,134 @@ .. _distributions: =========================== -Distribution-specific notes +Distribution-specific notes =========================== -The installation of Bcfg2 on a specific distribution depends on -the used package management tool and the disposability in the -distribution's package :term:`repository` -. +The installation of Bcfg2 on a specific distribution depends on the +package management tool and the availability of the package in the +distribution's repository. -.. toctree:: - :glob: +ArchLinux +========= - distro/* +Packages for `Arch Linux`_ are available in the Arch User Repository (AUR_). +Just use `pacman` to perform the installation :: + + pacman -S bcfg2 bcfg2-server + +.. _Arch Linux: http://www.archlinux.org/ +.. _AUR: http://aur.archlinux.org/packages.php?ID=20979 + +Debian +====== + +Packages of Bcfg2 are available for Debian Lenny, Debian Squeeze, and +Debian Sid. The fastest way to get Bcfg2 onto your Debian system +is to use ``apt-get`` or ``aptitude``. :: + + sudo aptitude install bcfg2 bcfg2-server + +If you want to use unofficial packages from Bcfg2 see the instructions +at `CustomDebianRepository`_. + +.. _CustomDebianRepository: http://trac.mcs.anl.gov/projects/bcfg2/wiki/PrecompiledPackages#UnofficialDebianRepository + +Fedora +====== + +The fastest way to get Bcfg2 Packages_ onto your Fedora_ system is to +use `yum` or PackageKit. Yum will pull in all dependencies of Bcfg2 +automatically. :: + + su -c 'yum install bcfg2-server bcfg2' + +Be aware that the latest release of Bcfg2 may only be available for the +Development release of Fedora (Rawhide). With the activation of the +Rawhide repository of Fedora you will be able to install it. :: + + su -c 'yum install --enablerepo=rawhide bcfg2-server bcfg2' + +This way is not recommended on production systems. Only for testing. + +Gentoo +====== + +Early in July 2008, Bcfg2 was added to the Gentoo portage tree. So far +it's still keyworded for all architectures, but we are actively working +to get it marked as stable. + +If you don't use portage to install Bcfg2, you'll want to make sure you +have all the prerequisites installed first. For a server, you'll need: + +* ``app-admin/gamin`` or ``app-admin/fam`` +* ``dev-python/lxml`` + +Clients will need at least: + +* ``app-portage/gentoolkit`` + +OS X +==== + +Bcfg2 can be installed either via MacPorts or by creating a native OS X +package. + +MacPorts +-------- + +Once macports is installed:: + + port install bcfg2 + +Using native OS X python +------------------------ + +First, make sure you have Xcode installed as you need ``packagemaker`` which +comes bundled in the Developer tools. + +Clone the git source:: + + git clone git://git.mcs.anl.gov/bcfg2.git + +Change to the osx directory and type make. Your new package should be +located at bcfg2-$VERSION.pkg (where $VERSION is that which is specified +in setup.py). + +RHEL / Centos / Scientific Linux +================================ + +While you can go about building all these things from source, this +section will try and meet the dependencies using packages from EPEL_ +[#f1]_. The *el5* and the soon available *el6* package should be compatible +with `CentOS`_ 5.x/6.x and `Scientific Linux`_. + +EPEL_:: + + [root@centos ~]# rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-4.noarch.rpm + +Install the bcfg2-server and bcfg2 RPMs:: + + [root@centos ~]# yum install bcfg2-server bcfg2 + +.. note:: + + The latest package for *el5* is only available in the testing repository. + +.. [#f1] For more details check the EPEL_ `instructions <http://fedoraproject.org/wiki/EPEL/FAQ#howtouse>`_ + +.. _CentOS: http://www.centos.org/ +.. _Scientific Linux: http://www.scientificlinux.org/ +.. _EPEL: http://fedoraproject.org/wiki/EPEL +.. _RPMForge: https://rpmrepo.org/RPMforge + +Ubuntu +====== + +We highly recommend following the instructions at `ubuntu-installation`_ +in order to install a recent version of Bcfg2 on your system. However, +if you would like to install the older package, you can use the following +command:: + + sudo aptitude install bcfg2 bcfg2-server + +.. _ubuntu-installation: http://trac.mcs.anl.gov/projects/bcfg2/wiki/PrecompiledPackages#UbuntuLaunchpadBcfg2PPA diff --git a/doc/installation/distro/archlinux.txt b/doc/installation/distro/archlinux.txt deleted file mode 100644 index 75ff59c49..000000000 --- a/doc/installation/distro/archlinux.txt +++ /dev/null @@ -1,17 +0,0 @@ -.. -*- mode: rst -*- - -.. _installation-archlinux: - -.. _Arch Linux: http://www.archlinux.org/ -.. _AUR: http://aur.archlinux.org/packages.php?ID=20979 - - -ArchLinux -========= - -Packages for `Arch Linux`_ are available in the Arch User Repository (AUR_). -Just use `pacman` to perform the installation :: - - pacman -S bcfg2 bcfg2-server - - diff --git a/doc/installation/distro/debian.txt b/doc/installation/distro/debian.txt deleted file mode 100644 index 67a4f1d9d..000000000 --- a/doc/installation/distro/debian.txt +++ /dev/null @@ -1,24 +0,0 @@ -.. -*- mode: rst -*- - -.. _debian: - -.. _Wiki: http://trac.mcs.anl.gov/projects/bcfg2/wiki/PrecompiledPackages#UnofficialDebianRepository - -Debian -====== - -Packages of Bcfg2 are available for Debian Lenny, Debian Squeeze, and -Debian Sid. The fastest way to get Bcfg2 onto your Debian system -is to use `apt-get` or `aptitude`. :: - - sudo aptitude install bcfg2 bcfg2-server - -If you want to use unofficial packages from Bcfg2. Add the following line -to your `/etc/apt/sources.list` file :: - - deb ftp://ftp.mcs.anl.gov/pub/bcfg/debian sarge/ - -Now just run `aptitute` in the way it is mentioned above. - -For more details about running prerelease version of Bcfg2 on Debian -systems, please refer to the Wiki_. diff --git a/doc/installation/distro/fedora.txt b/doc/installation/distro/fedora.txt deleted file mode 100644 index 92771b974..000000000 --- a/doc/installation/distro/fedora.txt +++ /dev/null @@ -1,23 +0,0 @@ -.. -*- mode: rst -*- - -.. _Packages: https://admin.fedoraproject.org/pkgdb/acls/name/bcfg2 -.. _Fedora: https://www.fedoraproject.org - -.. _fedora-installation: - -Fedora -====== - -The fastest way to get Bcfg2 Packages_ onto your Fedora_ system is to -use `yum` or PackageKit. Yum will pull in all dependencies of Bcfg2 -automatically. :: - - $ su -c 'yum install bcfg2-server bcfg2' - -Be aware that the latest release of Bcfg2 may only be available for the -Development release of Fedora (Rawhide). With the activation of the -Rawhide repository of Fedora you will be able to install it. :: - - $ su -c 'yum install --enablerepo=rawhide bcfg2-server bcfg2' - -This way is not recommanded on productive systems. Only for testing. diff --git a/doc/installation/distro/gentoo.txt b/doc/installation/distro/gentoo.txt deleted file mode 100644 index 5497a01b2..000000000 --- a/doc/installation/distro/gentoo.txt +++ /dev/null @@ -1,27 +0,0 @@ -.. -*- mode: rst -*- - -.. _gentoo-installation: - -.. _Freenode: http://chat.freenode.net -.. _#bcfg2: irc://chat.freenode.net/bcfg2 - - -Gentoo -====== - -Early in July 2008, Bcfg2 was added to the Gentoo portage tree. So far -it's only keyworded for ~x86, but we hope to see it soon in the amd64 and -x64-solaris ports. If you're using Gentoo on some other architecture, it -should still work provided that you have a reasonably up to date Python; -try adding `app-admin/bcfg2 ~*` to your `/etc/portage/package.keywords` -file. - -If you don’t use portage to install Bcfg2, you’ll want to make sure you -have all the prerequisites installed first. For a server, you’ll need: - -* ``app-admin/gamin`` or ``app-admin/fam`` -* ``dev-python/lxml`` - -Clients will need at least: - -* ``app-portage/gentoolkit`` diff --git a/doc/installation/distro/osx.txt b/doc/installation/distro/osx.txt deleted file mode 100644 index 8b7a5a95d..000000000 --- a/doc/installation/distro/osx.txt +++ /dev/null @@ -1,29 +0,0 @@ -.. -*- mode: rst -*- - -.. _osx-installation: - -.. _Freenode: http://chat.freenode.net -.. _#bcfg2: irc://chat.freenode.net/bcfg2 - - -OS X -==== - -Once macports is installed:: - - port install bcfg2 - -Using native OS X python ------------------------- - -First, make sure you have Xcode installed as you need `packagemaker` which -comes bundled in the Developer tools. - -Clone the git source:: - - git clone git://git.mcs.anl.gov/bcfg2.git - -Change to the osx directory and type make. Your new package should be located -at bcfg2-'''$VERSION'''.pkg (where '''$VERSION''' is that which is specified -in setup.py). - diff --git a/doc/installation/distro/rhel.txt b/doc/installation/distro/rhel.txt deleted file mode 100644 index 49e43179f..000000000 --- a/doc/installation/distro/rhel.txt +++ /dev/null @@ -1,31 +0,0 @@ -.. -*- mode: rst -*- - -.. _CentOS: http://www.centos.org/ -.. _Red Hat/RHEL: http://www.redhat.com/rhel/ -.. _Scientific Linux: http://www.scientificlinux.org/ -.. _EPEL: http://fedoraproject.org/wiki/EPEL -.. _RPMForge: https://rpmrepo.org/RPMforge - -.. _rhel-installation: - -RHEL / Centos / Scientific Linux -================================ - -While you can go about building all these things from source, this -section will try and meet the dependencies using packages from EPEL_ -[#f1]_. The *el5* and the soon available *el6* package should be compatible -with `CentOS`_ 5.x/6.x and `Scientific Linux`_. - -EPEL_:: - - [root@centos ~]# rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-4.noarch.rpm - -Install the bcfg2-server and bcfg2 RPMs:: - - [root@centos ~]# yum install bcfg2-server bcfg2 - -.. note:: - - The latest package for *el5* is only available in the testing repository. - -.. [#f1] For more details check the EPEL_ `instructions <http://fedoraproject.org/wiki/EPEL/FAQ#howtouse>`_ diff --git a/doc/installation/distro/ubuntu.txt b/doc/installation/distro/ubuntu.txt deleted file mode 100644 index 694cce865..000000000 --- a/doc/installation/distro/ubuntu.txt +++ /dev/null @@ -1,36 +0,0 @@ -.. -*- mode: rst -*- - -.. _ubuntu-installation: - -.. _Ubuntu: http://www.ubuntu.com -.. _Wiki: http://trac.mcs.anl.gov/projects/bcfg2/wiki/PrecompiledPackages#UbuntuLaunchpadBcfg2PPA - -Ubuntu -====== - -The steps to bring Bcfg2 onto your Ubuntu_ system depends on your -release. - -* Dapper - Add the following lines to `/etc/apt/sources.list` :: - - deb ftp://ftp.mcs.anl.gov/pub/bcfg/ubuntu dapper/ - deb http://archive.ubuntu.com/ubuntu dapper universe - deb-src http://archive.ubuntu.com/ubuntu dapper universe - -* Edgy - Add the following lines to `/etc/apt/sources.list` :: - - deb ftp://ftp.mcs.anl.gov/pub/bcfg/ubuntu edgy/ - deb http://archive.ubuntu.com/ubuntu edgy universe - deb-src http://archive.ubuntu.com/ubuntu edgy universe - -* Feisty - Those packages are available from the Ubuntu_ repositories. - -To install the packages, just lauch the following command :: - - sudo aptitude install bcfg2 bcfg2-server - -For more details about running prerelease version of Bcfg2 on Ubuntu_ -systems, please refer to the Wiki_. diff --git a/doc/installation/packages.txt b/doc/installation/packages.txt index a15e3e98e..b175d2625 100644 --- a/doc/installation/packages.txt +++ b/doc/installation/packages.txt @@ -9,34 +9,34 @@ .. _RPMForge: https://rpmrepo.org/RPMforge -Building packages from source -============================= +Building RPM packages from source +================================= The Bcfg2 distribution contains two different spec files. Building from Tarball --------------------- -* Copy the tarball to `/usr/src/packages/SOURCES/` -* Extract another copy of it somewhere else (eg: `/tmp`) and retrieve - the `misc/bcfg2.spec` file +* Copy the tarball to ``/usr/src/packages/SOURCES/`` +* Extract another copy of it somewhere else (eg: ``/tmp``) and retrieve + the ``misc/bcfg2.spec`` file * Run :: - rpmbuild -ba bcfg2.spec + rpmbuild -ba bcfg2.spec -* The resulting RPMs will be in `/usr/src/packages/RPMS/` and SRPMs - in `/usr/src/packages/SRPMS` +* The resulting RPMs will be in ``/usr/src/packages/RPMS/`` and SRPMs + in ``/usr/src/packages/SRPMS`` Building from an GIT Checkout ----------------------------- -* Change to the `redhat/` directory in the working copy +* Change to the ``redhat/`` directory in the working copy * Run :: make -* The resulting RPMs will be in `/usr/src/redhat/RPMS/ `and SRPMs - in `/usr/src/redhat/SRPMS` and will have the SVN revision appended +* The resulting RPMs will be in ``/usr/src/redhat/RPMS/`` and SRPMs + in ``/usr/src/redhat/SRPMS`` and will have the SVN revision appended Building RPM packages with ``rpmbuild`` --------------------------------------- @@ -47,35 +47,35 @@ The *el5* package should be compatible with CentOS 5.x. * Installation of the EPEL_ repository package :: - [root@centos ~]# rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-4.noarch.rpm + [root@centos ~]# rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-4.noarch.rpm * Now you can install the rest of the prerequisites :: - [root@centos ~]# yum install python-genshi python-cheetah python-lxml + [root@centos ~]# yum install python-genshi python-cheetah python-lxml * After installing git, check out the master branch :: - [root@centos redhat]# git clone git://git.mcs.anl.gov/bcfg2.git + [root@centos redhat]# git clone git://git.mcs.anl.gov/bcfg2.git * Install the ``fedora-packager`` package :: - [root@centos ~]# yum install fedora-packager + [root@centos ~]# yum install fedora-packager * A directory structure for the RPM build process has to be established. :: - [you@centos ~]$ rpmdev-setuptree + [you@centos ~]$ rpmdev-setuptree * Change to the *redhat* directory of the checked out Bcfg2 source:: - [you@centos ~]$ cd bcfg2/redhat/ + [you@centos ~]$ cd bcfg2/redhat/ -* In the particular directory is a ``Makefile`` which will do the job of +* In the particular directory is a ``Makefile`` which will do the job of building the RPM packages. You can do this as root, but it's not recommanded :: - [you@centos redhat]$ make + [you@centos redhat]$ make * Now the new RPM package can be installed. Please adjust the path to your RPM package :: - [root@centos ~]# rpm -ihv /home/YOU/rpmbuild/RPMS/noarch/bcfg2-server-1.0.0-0.2r5835.noarch.rpm + [root@centos ~]# rpm -ihv /home/YOU/rpmbuild/RPMS/noarch/bcfg2-server-1.0.0-0.2r5835.noarch.rpm diff --git a/doc/installation/prerequisites.txt b/doc/installation/prerequisites.txt index e4ea715b0..758ee4a21 100644 --- a/doc/installation/prerequisites.txt +++ b/doc/installation/prerequisites.txt @@ -14,16 +14,22 @@ what software is needed on the client and server side. Bcfg2 Client ------------ -===================================== =================== ============================== -Software Version Requires -===================================== =================== ============================== -libxml2 (if lxml is used) Any -libxslt (if lxml is used) Any libxml2 -python 2.3-2.4, 2.5 [#f1]_ -lxml or elementtree [#f2]_ Any lxml: libxml2, libxslt, python -python-apt [#f3]_ Any python -debsums (if APT tool driver is used) Any -===================================== =================== ============================== ++----------------------------+---------------+--------------------------------+ +| Software | Version | Requires | ++============================+===============+================================+ +| libxml2 (if lxml is used) | Any | | ++----------------------------+---------------+--------------------------------+ +| libxslt (if lxml is used) | Any | libxml2 | ++----------------------------+---------------+--------------------------------+ +| python | >= 2.3 [#f1]_ | | ++----------------------------+---------------+--------------------------------+ +| lxml or elementtree [#f2]_ | Any | lxml: libxml2, libxslt, python | ++----------------------------+---------------+--------------------------------+ +| python-apt [#f3]_ | Any | python | ++----------------------------+---------------+--------------------------------+ +| debsums (if APT tool | Any | | +| driver is used) | | | ++----------------------------+---------------+--------------------------------+ .. [#f1] python 2.5 works with elementtree. @@ -33,15 +39,20 @@ debsums (if APT tool driver is used) Any Bcfg2 Server ------------ -===================================== ============= ============================== -Software Version Requires -===================================== ============= ============================== -libxml2 2.6.24+ -libxslt Any libxml2 -python 2.2-2.5 -lxml 0.9+ lxml: libxml2, libxslt, python -gamin or fam Any -python-gamin or python-fam Any gamin or fam, python -M2crypto Any python, openssl -===================================== ============= ============================== - ++----------------------------+----------+--------------------------------+ +| Software | Version | Requires | ++============================+==========+================================+ +| libxml2 | 2.6.24+ | | ++----------------------------+----------+--------------------------------+ +| libxslt | Any | libxml2 | ++----------------------------+----------+--------------------------------+ +| python | 2.2-2.5 | | ++----------------------------+----------+--------------------------------+ +| lxml | 0.9+ | lxml: libxml2, libxslt, python | ++----------------------------+----------+--------------------------------+ +| gamin or fam | Any | | ++----------------------------+----------+--------------------------------+ +| python-gamin or python-fam | Any | gamin or fam, python | ++----------------------------+----------+--------------------------------+ +| M2crypto | Any | python, openssl | ++----------------------------+----------+--------------------------------+ diff --git a/doc/installation/source.txt b/doc/installation/source.txt index e21f7150f..3ea0404ad 100644 --- a/doc/installation/source.txt +++ b/doc/installation/source.txt @@ -1,64 +1,46 @@ .. -*- mode: rst -*- -.. _Download: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Download -.. _GPG: http://pgpkeys.mit.edu:11371/pks/lookup?op=get&search=0x75BF2C177F7D197E -.. _GPGKey: ftp://ftp.mcs.anl.gov/pub/bcfg/bcfg2-1.1.0.tar.gz.gpg -.. _Tarball: ftp://ftp.mcs.anl.gov/pub/bcfg/bcfg2-1.1.0.tar.gz - -.. |md5sum| replace:: 13593938daf7e8b9a81cb4b677dc7f99 -.. |version| replace:: 1.1.0 -.. |rel_date| replace:: 9/27/10 +.. _GPG1: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x75BF2C177F7D197E +.. _GPG2: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x80B8492FA88FFF4B .. _source: +Installation from source +======================== + Download -======== +-------- Tarball -------- +^^^^^^^ The Bcfg2 source tarball can be grabbed from the Download_ page. -========= ======== ======= ============== ===================== -Version URL GPG key Release Date md5sum -========= ======== ======= ============== ===================== -|version| Tarball_ GPGKey_ |rel_date| |md5sum| -========= ======== ======= ============== ===================== - -The full command to use with ``wget`` are listed below. Please -replace ``<version>`` with |version|. :: - - wget ftp://ftp.mcs.anl.gov/pub/bcfg/bcfg2-<version>.tar.gz - wget ftp://ftp.mcs.anl.gov/pub/bcfg/bcfg2-<version>.tar.gz.gpg - -All tarballs are signed with GPG key `7F7D197E <GPGKey>`_. You can verify -your download by importing the key and running :: - - $ gpg --recv-keys 0x75bf2c177f7d197e - $ gpg --verify bcfg2-<version>.tar.gz.gpg bcfg2-<version>.tar.gz - -For older or prepreleases please visit the Download_ wiki page. +All tarballs are signed with GPG keys `7F7D197E <GPG1>`_ or `A88FFF4B +<GPG2>`_. You can verify your download by importing the keys and running :: + gpg --recv-keys 0x75bf2c177f7d197e 0x80B8492FA88FFF4B + gpg --verify bcfg2-<version>.tar.gz.gpg bcfg2-<version>.tar.gz Git checkout ------------- +^^^^^^^^^^^^ You can also get the latest (possibly broken) code via git :: - git clone git://git.mcs.anl.gov/bcfg2.git + git clone git://git.mcs.anl.gov/bcfg2.git -Installation from source -======================== +Install +------- If you are working with the release tarball of Bcfg2 you need to untar it before you can go on with the installation :: - tar -xzf bcfg2-<version>.tar.gz + tar -xzf bcfg2-<version>.tar.gz -Now you can build Bcfg2 with. If you are working with a SVN checkout -no <version> need to be specified. :: +Now you can build Bcfg2 with. If you are working from a git clone no +<version> need to be specified. :: - cd bcfg2-<version> - python setup.py install --prefix=/install/prefix + cd bcfg2-<version> + python setup.py install --prefix=/install/prefix This will install both the client and server on that machine. diff --git a/doc/reports/dynamic.txt b/doc/reports/dynamic.txt index 1ec41af64..f798529eb 100644 --- a/doc/reports/dynamic.txt +++ b/doc/reports/dynamic.txt @@ -39,7 +39,8 @@ The recommended statistics plugin is DBStats. To use it, add it to the plugin can be used in conjunction with a crontab entry to run ``/usr/sbin/bcfg2-admin reports load_stats``. -Detailed installation instructions can be found :ref:`here <server-reports-install>`. +Detailed installation instructions can be found :ref:`here +<appendix-guides-web-reports-install>`. .. _dynamic-http-install: diff --git a/doc/reports/static.txt b/doc/reports/static.txt index d5d96fe12..67ba38a14 100644 --- a/doc/reports/static.txt +++ b/doc/reports/static.txt @@ -30,7 +30,7 @@ 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 +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 @@ -53,7 +53,7 @@ Output ====== Several output reports can be generated from the statistics store with -the command line tool {{{bcfg2-build-reports}}}. +the command line tool ``bcfg2-build-reports``. * Nodes Digest * Nodes Individual diff --git a/doc/server/plugins/connectors/properties.txt b/doc/server/plugins/connectors/properties.txt index 707de0880..afe3cd955 100644 --- a/doc/server/plugins/connectors/properties.txt +++ b/doc/server/plugins/connectors/properties.txt @@ -14,8 +14,8 @@ Enabling Properties First, ``mkdir /var/lib/bcfg2/Properties``. Each property XML file goes in this directory. Each will automatically be cached by the server, -and reread/reparsed upon changes. Add **Properties** to your `plugins` -line in `/etc/bcfg2.conf`. +and reread/reparsed upon changes. Add **Properties** to your ``plugins`` +line in ``/etc/bcfg2.conf``. Data Structures =============== @@ -27,9 +27,9 @@ contain parsed XML data as the "data" attribute. Usage ===== -Specific property files can be referred to in templates as -metadata.Properties[<filename>]. The data attribute is an LXML element object. -(Documented +Specific property files can be referred to in +templates as metadata.Properties[<filename>]. The +data attribute is an LXML element object. (Documented `here <http://codespeak.net/lxml/tutorial.html#the-element-class>`_) Currently, no access methods are defined for this data, but as we @@ -39,6 +39,7 @@ as methods. This will simplify templates. Accessing Properties contest from TGenshi ========================================= -Access contents of `Properties/auth.xml` :: +Access contents of ``Properties/auth.xml``:: + ${metadata.Properties['auth.xml'].data.find('file').find('bcfg2.key').text} diff --git a/doc/server/plugins/generators/tcheetah.txt b/doc/server/plugins/generators/tcheetah.txt index e1ad600a2..185b25ef5 100644 --- a/doc/server/plugins/generators/tcheetah.txt +++ b/doc/server/plugins/generators/tcheetah.txt @@ -27,7 +27,7 @@ located in in a ``TCheetah`` subdirectory of your repository, usually files, ``template`` and ``info``. The template is a standard Cheetah template with two additions: -* `self.metadata` is the client's metadata +* `self.metadata` is the client's :ref:`metadata <server-plugins-grouping-metadata-clientmetadata>` * `self.properties` is an xml document of unstructured data The ``info`` file is formatted like ``:info`` files from Cfg. @@ -44,19 +44,8 @@ Permissions entry and a Path entry to handle the same file. self.metadata variables ======================= -The following variables are available for self.metadata: - -* hostname -* bundles -* groups -* categories -* probes -* 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 and documented +:ref:`here <server-plugins-grouping-metadata-clientmetadata>`. self.properties =============== diff --git a/doc/server/plugins/generators/tgenshi/index.txt b/doc/server/plugins/generators/tgenshi/index.txt index cd9bcf152..425b3a289 100644 --- a/doc/server/plugins/generators/tgenshi/index.txt +++ b/doc/server/plugins/generators/tgenshi/index.txt @@ -48,8 +48,10 @@ supported. Inside of templates =================== -* metadata is the client's metadata -* properties.properties is an xml document of unstructured data +* **metadata** is the client's :ref:`metadata <server-plugins-grouping-metadata-clientmetadata>` +* **properties.properties** is an xml document of unstructured data +* **name** is the path name specified in bcfg +* **path** is the path to the TGenshi template See the genshi `documentation <http://genshi.edgewall.org/wiki/Documentation>`_ for examples of diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt index 96fc70ff5..fc452eb2f 100644 --- a/doc/server/plugins/grouping/metadata.txt +++ b/doc/server/plugins/grouping/metadata.txt @@ -225,3 +225,69 @@ Probes The metadata plugin includes client-side probing functionality. This is fully documented :ref:`here <server-plugins-probes-index>`. + +.. _server-plugins-grouping-metadata-clientmetadata: + +ClientMetadata +============== + +A special client metadata class is available to the TGenshi and TCheetah +plugins. + ++----------------------+------------------------------------------------+-------------------+ +| Attribute | Description | Value | ++======================+================================================+===================+ +| hostname | Client hostname | String | ++----------------------+------------------------------------------------+-------------------+ +| profile | Client profile | String | ++----------------------+------------------------------------------------+-------------------+ +| aliases | Client aliases | List | ++----------------------+------------------------------------------------+-------------------+ +| addresses | Adresses this client is known by | List | ++----------------------+------------------------------------------------+-------------------+ +| groups | Groups this client is a member of | List | ++----------------------+------------------------------------------------+-------------------+ +| categories | Categories of this clients groups | List | ++----------------------+------------------------------------------------+-------------------+ +| uuid | uuid identifier for this client | String | ++----------------------+------------------------------------------------+-------------------+ +| password | bcfg password for this client | String | ++----------------------+------------------------------------------------+-------------------+ +| connectors | connector plugins known to this client | List | ++----------------------+------------------------------------------------+-------------------+ +| query | MetadataQuery object | MetadataQuery | ++----------------------+------------------------------------------------+-------------------+ + +| + ++------------------------------+------------------------------------------------+-------------------+ +| Method | Description | Value | ++==============================+================================================+===================+ +| inGroup(group) | True if this client is a memnber of 'group' | Boolean | ++------------------------------+------------------------------------------------+-------------------+ +| group_in_category(category) | Returns the group in 'category' if the client | String | +| | is a member of 'category', otherwise '' | | ++------------------------------+------------------------------------------------+-------------------+ + +MetadataQuery +------------- + +This class provides query routines for the servers Metadata. + ++------------------------------+------------------------------------------------+-------------------+ +| Method | Description | Value | ++==============================+================================================+===================+ +| by_name(client) | Get ClientMetadata object for 'client' | ClientMetadata | ++------------------------------+------------------------------------------------+-------------------+ +| names_by_groups(group) | | | ++------------------------------+------------------------------------------------+-------------------+ +| names_by_profiles(profile) | All clients names in 'profile' | List | ++------------------------------+------------------------------------------------+-------------------+ +| all_clients() | All known client hostnames | List | ++------------------------------+------------------------------------------------+-------------------+ +| all_groups() | All known group names | List | ++------------------------------+------------------------------------------------+-------------------+ +| all_groups_in_category(cat) | All groups in category 'cat' | List | ++------------------------------+------------------------------------------------+-------------------+ +| all() | Get ClientMetadata for all clients | List | ++------------------------------+------------------------------------------------+-------------------+ diff --git a/doc/server/plugins/index.txt b/doc/server/plugins/index.txt index e561722cf..61f91da86 100644 --- a/doc/server/plugins/index.txt +++ b/doc/server/plugins/index.txt @@ -30,18 +30,6 @@ http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/src/lib/Server/Plugin .. _Bcfg2 repository: http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/src/lib/Server/Plugins. -Connectors ----------- - -.. toctree:: - :maxdepth: 2 - :glob: - - connectors/* - -Each of these plugins has a corresponding subdirectory with the same -name in the Bcfg2 repository. - Metadata (Grouping) ------------------- @@ -80,6 +68,15 @@ Literal Configuration (Generators) Each of these plugins has a corresponding subdirectory with the same name in the Bcfg2 repository. +Connector Plugins +----------------- + +.. toctree:: + :maxdepth: 2 + :glob: + + connectors/* + Statistics Plugins ------------------ @@ -90,7 +87,7 @@ Statistics Plugins statistics/* DBStats can be enabled by adding it to the plugins line in -`/etc/bcfg2.conf`. +``/etc/bcfg2.conf``. Version Plugins --------------- diff --git a/doc/server/plugins/structures/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt index 7b4cd7b6f..da49b299e 100644 --- a/doc/server/plugins/structures/bundler/index.txt +++ b/doc/server/plugins/structures/bundler/index.txt @@ -29,7 +29,7 @@ The following is an annotated copy of a bundle: .. code-block:: xml - <Bundle name='ssh' version='2.0'> + <Bundle name='ssh' version='2.0'> <Path name='/etc/ssh/ssh_host_dsa_key'/> <Path name='/etc/ssh/ssh_host_rsa_key'/> <Path name='/etc/ssh/ssh_host_dsa_key.pub'/> diff --git a/doc/unsorted/bcfg2.conf-options.txt b/doc/unsorted/bcfg2.conf-options.txt new file mode 100644 index 000000000..57e26cbd2 --- /dev/null +++ b/doc/unsorted/bcfg2.conf-options.txt @@ -0,0 +1,19 @@ +.. -*- mode: rst -*- + +.. _unsorted-bcfg2.conf-options: + +========== +bcfg2.conf +========== + +This page documents the various options available in bcfg2.conf. The +various sections correspond to the sections in the file itself. + +components +========== + +logging +------- + +Specify an alternate path for the lockfile used by the bcfg2 client. +Default value is ``/var/lock/bcfg2.run`` diff --git a/doc/development/emacs_snippet.txt b/doc/unsorted/emacs_snippet.txt index 2905a2b45..b9f7fd25b 100644 --- a/doc/development/emacs_snippet.txt +++ b/doc/unsorted/emacs_snippet.txt @@ -1,6 +1,6 @@ .. -*- mode: rst -*- -.. _development-emacs_snippet: +.. _unsorted-emacs_snippet: ====================== Emacs + YASnippet mode diff --git a/doc/development/vim_snippet.txt b/doc/unsorted/vim_snippet.txt index a01c1cfda..e4fda7eca 100644 --- a/doc/development/vim_snippet.txt +++ b/doc/unsorted/vim_snippet.txt @@ -1,6 +1,6 @@ .. -*- mode: rst -*- -.. _development-vim_snippet: +.. _unsorted-vim_snippet: =================== Vim Snippet Support @@ -53,13 +53,13 @@ that allow quick composition of bundles and base files. <Permissions name='${1:name}'/> -#. Save and start editing away! +#. Save and start editing away! -Each of these snippets activates on the opening element, ie <Bundle>. -After this string is entered, but before entering a space, press <TAB>, -and the snippet will be expanded. The template will be inserted into -the text with a set of input prompts, which default to overwrite mode +Each of these snippets activates on the opening element, ie <Bundle>. +After this string is entered, but before entering a space, press <TAB>, +and the snippet will be expanded. The template will be inserted into +the text with a set of input prompts, which default to overwrite mode and can be tabbed through. -The code above only works for bundles and base, but will be expanded -to support other xml files as well. +The code above only works for bundles and base, but will be expanded +to support other xml files as well. diff --git a/doc/unsorted/writing_specification.txt b/doc/unsorted/writing_specification.txt index 5a75165bf..3201067f0 100644 --- a/doc/unsorted/writing_specification.txt +++ b/doc/unsorted/writing_specification.txt @@ -14,8 +14,8 @@ Bcfg2 specifications are logically divided in to three areas: The metadata portion of the configuration assigns a client to its profile group and to its non-profile groups. The profile group is assigned -in Metadata/clients.xml and the non profile group assignments are in -Metadata/groups.xml. +in ``Metadata/clients.xml`` and the non profile group assignments are in +``Metadata/groups.xml``. The group memberships contained in the metadata are then used to constuct an abstract configuration for the client. An abstract configuration for |