diff options
Diffstat (limited to 'doc')
49 files changed, 1163 insertions, 339 deletions
diff --git a/doc/appendix/guides/authentication.txt b/doc/appendix/guides/authentication.txt index b8ec82590..93a34c9bc 100644 --- a/doc/appendix/guides/authentication.txt +++ b/doc/appendix/guides/authentication.txt @@ -37,7 +37,6 @@ This is a :ref:`Cheetah template per-client bcfg2.conf from the per-client metadata:: [communication] - protocol = xmlrpc/ssl #if $self.metadata.uuid != None user = $self.metadata.uuid #end if diff --git a/doc/appendix/guides/centos.txt b/doc/appendix/guides/centos.txt index 3a35627a8..44ee08777 100644 --- a/doc/appendix/guides/centos.txt +++ b/doc/appendix/guides/centos.txt @@ -132,7 +132,6 @@ upon connection:: [communication] - protocol = xmlrpc/ssl password = N41lMNeW ca = /etc/bcfg2.crt @@ -230,10 +229,11 @@ should look something like this When editing your xml files by hand, it is useful to occasionally run `bcfg2-lint` to ensure that your xml validates properly. -The final thing we need is for the client to have the proper -arch group membership. For this, we will make use of the -:ref:`unsorted-dynamic_groups` capabilities of the Probes plugin. Add -Probes to your plugins line in ``bcfg2.conf`` and create the Probe.:: +The final thing we need is for the client to have the proper arch +group membership. For this, we will make use of the +:ref:`server-plugins-probes-dynamic-groups` capabilities of the Probes +plugin. Add Probes to your plugins line in ``bcfg2.conf`` and create +the Probe.:: [root@centos ~]# grep plugins /etc/bcfg2.conf plugins = Bundler,Cfg,...,Probes diff --git a/doc/appendix/guides/import-existing-ssh-keys.txt b/doc/appendix/guides/import-existing-ssh-keys.txt index 6ce41ba60..4e2282044 100644 --- a/doc/appendix/guides/import-existing-ssh-keys.txt +++ b/doc/appendix/guides/import-existing-ssh-keys.txt @@ -1,4 +1,5 @@ .. -*- mode: rst -*- +.. vim: ft=rst .. _appendix-guides-import-existing-ssh-keys: @@ -21,11 +22,24 @@ Add a bundle for ssh After verifying that SSHbase is listed on the plugins line in ``/etc/bcfg2.conf``, you need to create a bundle containing the -appropriate entries. +appropriate entries. In general, you can use a path glob: .. code-block:: xml <Bundle> + <Path glob="/etc/ssh/*"/> + </Bundle> + +If you need more granular control -- e.g., other entries in +``/etc/ssh`` are specified in other bundles -- you can also list the +files explicity: + +.. code-block:: xml + + <Bundle> + <!-- requires a version of openssh that can generate ecdsa keys --> + <Path name="/etc/ssh/ssh_host_ecdsa_key"/> + <Path name="/etc/ssh/ssh_host_ecdsa_key.pub"/> <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'/> @@ -83,7 +97,7 @@ Now, we pull the ssh host key data for the client out of the uploaded stats and insert it as host-specific copies of these files in ``/var/lib/bcfg2/SSHBase``.:: - for key in ssh_host_rsa_key ssh_host_dsa_key ssh_host_key; do + for key in ssh_host_ecdsa_key ssh_host_rsa_key ssh_host_dsa_key ssh_host_key; do sudo bcfg2-admin pull <clientname> Path /etc/ssh/$key sudo bcfg2-admin pull <clientname> Path /etc/ssh/$key.pub done diff --git a/doc/appendix/guides/sslca_howto.txt b/doc/appendix/guides/sslca_howto.txt index 9c939dcd3..8ee0b2b42 100644 --- a/doc/appendix/guides/sslca_howto.txt +++ b/doc/appendix/guides/sslca_howto.txt @@ -148,7 +148,6 @@ Here's what a functional **[communication]** section in a ``bcfg2.conf`` genshi template for clients might look like.:: [communication] - protocol = xmlrpc/ssl {% if metadata.uuid != None %}\ user = ${metadata.uuid} {% end %}\ diff --git a/doc/appendix/guides/ubuntu.txt b/doc/appendix/guides/ubuntu.txt index 60f8e3a41..24bebf023 100644 --- a/doc/appendix/guides/ubuntu.txt +++ b/doc/appendix/guides/ubuntu.txt @@ -172,7 +172,6 @@ Replace Pkgmgr with Packages in the plugins line of ``bcfg2.conf``:: transport = LocalFilesystem [communication] - protocol = xmlrpc/ssl password = secret certificate = /etc/ssl/bcfg2.crt key = /etc/ssl/bcfg2.key @@ -253,10 +252,11 @@ that our client is able to obtain these sources. When editing your xml files by hand, it is useful to occasionally run ``bcfg2-lint -v`` to ensure that your xml validates properly. -The last thing we need is for the client to have the proper -arch group membership. For this, we will make use of the -:ref:`unsorted-dynamic_groups` capabilities of the Probes plugin. Add -Probes to your plugins line in ``bcfg2.conf`` and create the Probe. +The last thing we need is for the client to have the proper arch group +membership. For this, we will make use of the +:ref:`server-plugins-probes-dynamic-groups` capabilities of the Probes +plugin. Add Probes to your plugins line in ``bcfg2.conf`` and create +the Probe. .. code-block:: sh diff --git a/doc/client/metadata.txt b/doc/client/metadata.txt index 27870ba9a..0dec5e3a7 100644 --- a/doc/client/metadata.txt +++ b/doc/client/metadata.txt @@ -1,4 +1,5 @@ .. -*- mode: rst -*- +.. vim: ft=rst .. _client-metadata: @@ -24,12 +25,12 @@ interaction: This construction process spans several server plugins. The :ref:`server-plugins-grouping-metadata` is responsible for initial instance creation, including the client hostname, -profile, and basic group memberships. After this initial creation, -Connector plugins (such as :ref:`server-plugins-probes-index` or -:ref:`server-plugins-connectors-properties`) can add additional group -memberships for clients. These memberships are merged into the instance; -that is, the new group memberships are treated as if they were included -in groups.xml. If any of these groups are defined in groups.xml, +profile, and basic group memberships. After this initial +creation, Connector plugins (such as :ref:`server-plugins-probes` +or :ref:`server-plugins-connectors-properties`) can add additional +group memberships for clients. These memberships are merged into the +instance; that is, the new group memberships are treated as if they were +included in groups.xml. If any of these groups are defined in groups.xml, then groups included there are included in the ClientMetadata instance group list. At the end of this process, the ClientMetadata instance has its complete set of group memberships. At this point, each connector diff --git a/doc/client/tools/augeas.txt b/doc/client/tools/augeas.txt new file mode 100644 index 000000000..6fed5f5ce --- /dev/null +++ b/doc/client/tools/augeas.txt @@ -0,0 +1,95 @@ +.. -*- mode: rst -*- + +.. _client-tools-augeas: + +======== + Augeas +======== + +The Augeas tool provides a way to use `Augeas +<http://www.augeas.net>`_ to edit files that may not be completely +managed. + +In the simplest case, you simply tell Augeas which path to edit, and +give it a sequence of commands: + +.. code-block:: xml + + <Path type="augeas" name="/etc/hosts" owner="root" group="root" + mode="0644"> + <Set path="01/ipaddr" value="192.168.0.1"/> + <Set path="01/canonical" value="pigiron.example.com"/> + <Set path="01/alias[1]" value="pigiron"/> + <Set path="01/alias[2]" value="piggy"/> + </Path> + +The commands are run in document order. There's no need to do an +explicit ``save`` at the end. + +These commands will be run if any of the paths do not already +have the given setting. In other words, if any command has not +already been run, they will all be run. + +So, if the first host already has all of the specified settings, then +that Path will verify successfully and nothing will be changed. But +suppose the first host looks like this:: + + 192.168.0.1 pigiron.example.com pigiron + +All that is missing is the second alias, ``piggy``. The entire Augeas +script will be run in this case. It's important, then, to ensure that +all commands you use are idempotent. (For instance, the ``Move`` and +``Insert`` commands are unlikely to be useful.) + +The Augeas paths are all relative to ``/files/etc/hosts``. + +The Augeas tool understands a subset of ``augtool`` commands. Valid +tags are: ``Remove``, ``Move``, ``Set``, ``Clear``, ``SetMulti``, and +``Insert``. Refer to the official Augeas docs or the `Schema`_ below +for details on the commands. + +The Augeas tool also supports one additional directive, ``Initial``, +for setting initial file content when a file does not exist. For +instance, the ``Xml`` lens fails to parse a file that does not exist, +and, as a result, you cannot add content to it. You can use +``Initial`` to circumvent this issue: + +.. code-block:: xml + + <Path type="augeas" name="/etc/test.xml" lens="Xml" + owner="root" group="root" mode="0640"> + <Initial><Test/></Initial> + <Set path="Test/#text" value="text content"/> + </Path> + +Editing files outside the default load path +=========================================== + +If you're using Augeas to edit files outside of its default load path, +you must manually specify the lens. For instance: + +.. code-block:: xml + + <Path type="augeas" name="/opt/jenkins/home/config.xml" lens="Xml" + owner="jenkins" group="jenkins" mode="0640"> + <Set path="hudson/systemMessage/#text" + value="This is a Jenkins server."/> + </Path> + +Note that there's no need to manually modify the load path by setting +``/augeas/load/<lens>/incl``, nor do you have to call ``load`` +explicitly. + +Schema +====== + +.. xml:group:: augeasCommands + + +Performance +=========== + +The Augeas tool is quite slow to initialize. For each ``<Path +type="augeas" ... >`` entry you have, it creates a new Augeas object +internally, which can take several seconds. It's thus important to +use this tool sparingly. diff --git a/doc/conf.py b/doc/conf.py index 0e4009cd3..1da6b3b01 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -64,9 +64,9 @@ else: # built documents. # # The short X.Y version. -version = '1.3' +version = '1.4' # The full version, including alpha/beta/rc tags. -release = '1.3.3' +release = '1.4.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/doc/contents.txt b/doc/contents.txt index 8220d0d1d..e7df568f9 100644 --- a/doc/contents.txt +++ b/doc/contents.txt @@ -21,6 +21,7 @@ Bcfg2 documentation |release| glossary appendix/index man/index + releases/index unsorted/index diff --git a/doc/development/caching.txt b/doc/development/caching.txt index 47d627278..83ec0290f 100644 --- a/doc/development/caching.txt +++ b/doc/development/caching.txt @@ -1,4 +1,5 @@ .. -*- mode: rst -*- +.. vim: ft=rst .. _development-cache: @@ -44,10 +45,10 @@ Currently known caches are: | Metadata | Hostname | :class:`ClientMetadata | The :ref:`Metadata cache <server-caching>` | | | | <Bcfg2.Server.Plugins.Metadata.ClientMetadata>` | | +-------------+---------------------------------------+-------------------------------------------------+------------------------------------------------------+ -| Probes, | Hostname | ``list`` of group names | Groups set by :ref:`server-plugins-probes-index` | +| Probes, | Hostname | ``list`` of group names | Groups set by :ref:`server-plugins-probes` | | probegroups | | | | +-------------+---------------------------------------+-------------------------------------------------+------------------------------------------------------+ -| Probes, | Hostname | ``dict`` of ``<probe name>``: | Other data set by :ref:`server-plugins-probes-index` | +| Probes, | Hostname | ``dict`` of ``<probe name>``: | Other data set by :ref:`server-plugins-probes` | | probedata | | :class:`ProbeData | | | | | <Bcfg2.Server.Plugins.Probes.ProbeData>` | | +-------------+---------------------------------------+-------------------------------------------------+------------------------------------------------------+ diff --git a/doc/development/cfg.txt b/doc/development/cfg.txt index f93bb42c7..4e967368b 100644 --- a/doc/development/cfg.txt +++ b/doc/development/cfg.txt @@ -64,9 +64,11 @@ Generators .. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgPlaintextGenerator.CfgPlaintextGenerator .. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgGenshiGenerator.CfgGenshiGenerator .. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgCheetahGenerator.CfgCheetahGenerator +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgJinja2Generator.CfgJinja2Generator .. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgEncryptedGenerator.CfgEncryptedGenerator .. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgEncryptedGenshiGenerator.CfgEncryptedGenshiGenerator .. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgEncryptedCheetahGenerator.CfgEncryptedCheetahGenerator +.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgEncryptedJinja2Generator.CfgEncryptedJinja2Generator .. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgAuthorizedKeysGenerator.CfgAuthorizedKeysGenerator Creators diff --git a/doc/development/plugins.txt b/doc/development/plugins.txt index e4f16b84d..5993c4e29 100644 --- a/doc/development/plugins.txt +++ b/doc/development/plugins.txt @@ -1,4 +1,5 @@ .. -*- mode: rst -*- +.. vim: ft=rst .. _development-plugins: @@ -147,9 +148,8 @@ For examples, see: * :func:`Bcfg2.Server.Plugins.Probes.ReceiveData` takes a copy of the groups that have been assigned to a client by - :ref:`server-plugins-probes-index`, and if that data changes when - new probe data is received, it invalidates the cache for that - client. + :ref:`server-plugins-probes`, and if that data changes when new probe + data is received, it invalidates the cache for that client. * :func:`Bcfg2.Server.Plugins.GroupPatterns.Index` expires the entire cache whenever a FAM event is received for the :ref:`server-plugins-grouping-grouppatterns` config file. diff --git a/doc/development/testing.txt b/doc/development/testing.txt index f00193574..b6db98cca 100644 --- a/doc/development/testing.txt +++ b/doc/development/testing.txt @@ -69,8 +69,8 @@ Server Testing Entry: fs13.bgl.mcs.anl.gov.xml Entry: fs13.bgl.mcs.anl.gov.xml good Entry: login1.bgl.mcs.anl.gov.xml - ConfigFile /bin/whatami contents differ - ConfigFile /bin/whatami differs (in bundle softenv) + Path /bin/whatami contents differ + Path /bin/whatami differs (in bundle softenv) Entry: login1.bgl.mcs.anl.gov.xml bad This can be used to compare configurations for single clients, or diff --git a/doc/exts/xmlschema.py b/doc/exts/xmlschema.py index c26aed81e..89104c2a6 100644 --- a/doc/exts/xmlschema.py +++ b/doc/exts/xmlschema.py @@ -784,7 +784,7 @@ class XMLDomain(Domain): def clear_doc(self, docname): to_del = [] for dtype in self.types.keys(): - for key, (doc, _) in self.data[dtype].iteritems(): + for key, (doc, _) in self.data[dtype].items(): if doc == docname: to_del.append((dtype, key)) for dtype, key in to_del: @@ -803,7 +803,7 @@ class XMLDomain(Domain): def get_objects(self): for dtype in self.types.keys(): - for name, (docname, tgtid) in self.data[dtype].iteritems(): + for name, (docname, tgtid) in self.data[dtype].items(): yield (name, name, dtype, docname, tgtid, self.object_types[dtype].attrs['searchprio']) diff --git a/doc/getting_started/index.txt b/doc/getting_started/index.txt index 9b69bf65a..f619447e2 100644 --- a/doc/getting_started/index.txt +++ b/doc/getting_started/index.txt @@ -223,7 +223,7 @@ you will find that we now have a correct entry:: Done! Now we just have 242 (or more) entries to take care of! -:ref:`server-plugins-structures-bundler-index` is a +:ref:`server-plugins-structures-bundler` is a relatively easy directory to populate. You can find many samples of Bundles in the :ref:`Bundler Example Repository <server-plugins-structures-bundler-index-examples>`, many of which can @@ -255,6 +255,10 @@ Once you have the server setup, you may be interested in Platform-specific Quickstart Notes ================================== -* :ref:`appendix-guides-centos` -* :ref:`appendix-guides-ubuntu` -* :ref:`getting_started-macosx-notes` +.. toctree:: + :maxdepth: 1 + + CentOS </appendix/guides/centos> + Ubuntu </appendix/guides/ubuntu> + Gentoo </appendix/guides/gentoo> + Mac OS X <macosx/notes> diff --git a/doc/installation/building-packages.txt b/doc/installation/building-packages.txt new file mode 100644 index 000000000..b3b775869 --- /dev/null +++ b/doc/installation/building-packages.txt @@ -0,0 +1,228 @@ +.. -*- mode: rst -*- +.. vim: ft=rst + +.. _installation-building-packages: + +============================= +Building packages from source +============================= + +Building RPMs +============= + +Building from a tarball +----------------------- + +* Create a directory structure for rpmbuild:: + + rpmdev-setuptree + +* Copy the tarball to ``~/rpmbuild/SOURCES/`` +* Extract another copy of it somewhere else (eg: ``/tmp``) and retrieve + the ``misc/bcfg2.spec`` file +* Run the following:: + + rpmbuild -ba bcfg2.spec + +* The resulting RPMs will be in ``~/rpmbuild/RPMS/`` and SRPMs + in ``~/rpmbuild/SRPMS/``. + +Building Debian packages +======================== + +The Bcfg2 project provides a ``debian`` subdirectory with the project's +source that enables users to create their own Debian/Ubuntu compatible +packages (`.deb` files). + +Build deps +---------- + +If the distribution you are building on already has packaged bcfg2 +(even an older version), the following command will likely install the +necessary build dependencies:: + + apt-get build-dep bcfg2 bcfg2-server + +Install source code +------------------- + +Depending on which version of bcfg2 you want build, you can obtain the +source code from the Download_ page or from the project's git repository. +To create a local anonymous working copy of the latest version of the +bcfg2 source code, use a command like the following:: + + git clone git://git.mcs.anl.gov/bcfg2.git + +Update the changelog +-------------------- + +The next step is to update the ``debian/changelog`` file with an +appropriate package version string. Debian packages contain a version +that is extracted from the latest entry in this file. An appropriate +version will help you distinguish your locally built package from one +provided by your distribution. It also helps the packaging system know +when a newer version of the package is available to install. + +It is possible to skip this step, but the packages you build will have +the same version as the source distribution and will be easy to confuse +with other similarly named (but maybe not equivalent) packages. + +The basic format of the package version string to use is this:: + + <UPSTREAM VER>~<UPSTREAM PRE-VER>+<GIT-ID>-0.1+<LOCAL VER> + +.. note:: + The '+', and '-' characters have significance in determining when + one package is newer than another. The following format is believed + to do the right thing in all common situations. + +The components of the package version string are explained below: + +.. glossary:: + + <UPSTREAM VER> + This is the version of the Bcfg source code you are working + from. It will likely be something like `0.9.6` or `1.0`. + + <UPSTREAM PRE-VER> + If you are using a published pre-release of Bcfg2, it will have + a name like `pre1` or `rc1`. Use that string here, otherwise + drop this component from the package version string. + + +<GIT-ID> + If you are building from a local working copy of the git + repository, it is useful to include the revision in the package + version. If you are building from a downloaded copy of the source, + drop this component (including the preceding plus-sign (`+`) + from the package version string. + + +<LOCAL VER> + This is a locally relevant name like your last name or your + domain name, plus the digit `1`. For example, if your family + name is ''Smith'', you could use `smith1`. If you work for + ''Example Inc'', you could use `example1`. + +Here are some examples: + +* If you are building packages for revision 6c681bd from git, and the + latest published version is 1.2.0rc1, the version string should be + `1.2.0rc1+6c681bd-0.1+example1`. +* If you are building packages for the published 1.0 rc1 version, the + version string should be `1.0rc1-0.1+example1`. +* If you are building packages for the published 1.0 version, the version + string should be `1.0-0.1+example1`. + +If you are working on a git working copy of 1.0 pre5 and have the +``devscripts`` package installed, the following command is a convenient +way to create a well formatted changelog entry:: + + REV=$(git log --oneline | head -n 1 | cut -d' ' -f1) + debchange --force-bad-version --preserve --newversion "1.0~pre5+${REV}-0.1+example1" git revision $REV + +Building the package +-------------------- + +With the preliminaries out of the way, building the package is simple.:: + + cd .. # Change into the top level of the source directory + fakeroot dpkg-buildpackage -uc -us + +The freshly built packages will be deposited in the parent of the +current directory (``..``). Examine the output of ``dpkg-buildpackage`` +for details. + +External build systems +---------------------- + +This section describes how to build bcfg2 and deps via external build +systems (Currently only a PPA). Some other possibilities are: + + * #651 Look into project-builder to make more native-system bcfg2 packages available + * http://en.opensuse.org/Build_Service/Deb_builds + +Launchpad PPA +^^^^^^^^^^^^^ + +https://launchpad.net/~bcfg2 + +To upload to the PPA you need to be on the active member list of `Bcfg2 +in Launchpad`_. + +Note that **after each successful upload**, you should wait until the PPA +is built, and then **install it locally** using ``sudo aptitude update; +sudo aptitude install (packagename)`` so the next build doesn't fail on +your local machine. If you don't want to wait for a PPA binary build to +complete, you can "apt-get source (packagename)" and do a local build +before the PPA build is done. + +setup gpg-agent +""""""""""""""" + +Setting up gpg-agent and pinentry prevents you from having to type your +passphrase repeatedly.:: + + sudo aptitude install gnupg-agent pinentry-gtk2 pinentry-curses + # replace 0xAA95C349 with your GPG Key ID + export GPGKEY=0xAA95C349 + killall -q gpg-agent + eval $(gpg-agent --daemon) + +setup debuild +""""""""""""" + +Tell dpkg-buildpackage who you are, for example:: + + export DEBEMAIL="dclark@pobox.com" + export DEBFULLNAME="Daniel Joseph Barnhart Clark" + +upload bcfg2 to ppa +""""""""""""""""""" + +A ``dists`` file contains a space-separated list of all distributions +you want to build PPA packages for. + +.. code-block:: sh + + #!/bin/sh + + . ./dists + + # Replace 0xAA95C349 with your GnuPG Key ID + export GPGKEY=0xAA95C349 + + sudo apt-get build-dep bcfg2 bcfg2-server + sudo aptitude install git + + VERSION=1.3.2-1 + if [ ! -d testing ]; then + mkdir testing + fi + DATE=$(date +%F-%H%M) + ppa="testing" # "testing" or "ppa" (for stable) + + # download source + cd testing + git clone git://git.mcs.anl.gov/bcfg2 + cd bcfg2 + GITID=$(git log --oneline | head -n 1 | cut -d' ' -f1) + cp debian/changelog ../changelog.orig + + for dist in $DISTS + do + cp ../changelog.orig debian/changelog + (cd debian && dch --distribution ${dist} \ + --force-bad-version \ + --preserve \ + --force-distribution \ + --newversion "${VERSION}~${ppa}~${dist}${DATE}+${GITID}" \ + "bcfg2 backport for ${dist} release ${VERSION} git commit ${GITID}") + debuild --no-tgz-check -rfakeroot -I -S -k${GPGKEY} + done + + for dist in $DISTS + do + dput ppa:bcfg2/${dist}testing ../bcfg2_${VERSION}~${ppa}~${dist}${DATE}+${GITID}_source.changes + done + +.. _Download: http://bcfg2.org/download/ +.. _Bcfg2 in Launchpad: https://launchpad.net/~bcfg2 diff --git a/doc/installation/distributions.txt b/doc/installation/distributions.txt index 9db111682..306439485 100644 --- a/doc/installation/distributions.txt +++ b/doc/installation/distributions.txt @@ -1,4 +1,5 @@ .. -*- mode: rst -*- +.. vim: ft=rst .. _distributions: @@ -103,10 +104,12 @@ section will try and meet the dependencies using packages from EPEL_ [#f1]_. The *el5* and the *el6* package should be compatible with `CentOS`_ 5.x/6.x and `Scientific Linux`_. -EPEL_ for 5.x :: +EPEL_ for 5.x:: + [root@centos ~]# rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-4.noarch.rpm -EPEL_ for 6.x :: +EPEL_ for 6.x:: + [root@centos ~]# rpm -Uvh http://download.fedoraproject.org/pub/epel/6/i386/epel-release-6-5.noarch.rpm Install the bcfg2-server and bcfg2 RPMs:: diff --git a/doc/installation/index.txt b/doc/installation/index.txt index 9f04d4b52..9bcf8be15 100644 --- a/doc/installation/index.txt +++ b/doc/installation/index.txt @@ -19,5 +19,5 @@ needs to be installed on any machine you plan to manage by Bcfg2. prerequisites source - packages + building-packages distributions diff --git a/doc/installation/packages.txt b/doc/installation/packages.txt deleted file mode 100644 index b23a870cf..000000000 --- a/doc/installation/packages.txt +++ /dev/null @@ -1,81 +0,0 @@ -.. -*- mode: rst -*- - -.. _packages: - -.. _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 - - -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 -* Run :: - - rpmbuild -ba bcfg2.spec - -* 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 -* 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 - -Building RPM packages with ``rpmbuild`` ---------------------------------------- - -While you can go about building all these things from source, this -how to will try and meet the dependencies using packages from EPEL_. -The *el5* and the *el6* 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-6.noarch.rpm - -* Now you can install the rest of the prerequisites :: - - [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 - -* Install the ``fedora-packager`` package :: - - [root@centos ~]# yum install fedora-packager - -* A directory structure for the RPM build process has to be established. :: - - [you@centos ~]$ rpmdev-setuptree - -* Change to the *redhat* directory of the checked out Bcfg2 source:: - - [you@centos ~]$ cd bcfg2/redhat/ - -* 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 - recommended:: - - [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 diff --git a/doc/installation/prerequisites.txt b/doc/installation/prerequisites.txt index 81ac12632..a30a3b26b 100644 --- a/doc/installation/prerequisites.txt +++ b/doc/installation/prerequisites.txt @@ -21,7 +21,7 @@ Bcfg2 Client +----------------------------+------------------------+--------------------------------+ | libxslt (if lxml is used) | Any | libxml2 | +----------------------------+------------------------+--------------------------------+ -| python | 2.4 and greater [#f1] | | +| python | 2.4 and greater [#f1]_ | | +----------------------------+------------------------+--------------------------------+ | lxml or elementtree [#f2]_ | Any | lxml: libxml2, libxslt, python | +----------------------------+------------------------+--------------------------------+ @@ -30,6 +30,8 @@ Bcfg2 Client | debsums (if APT tool | Any | | | driver is used) | | | +----------------------------+------------------------+--------------------------------+ +| python-setuptools | Any | | ++----------------------------+------------------------+--------------------------------+ .. [#f1] python 2.5 and later works with elementtree. @@ -54,10 +56,25 @@ Bcfg2 Server +-------------------------------+----------+--------------------------------+ | python-gamin or pyinotify | Any | gamin or inotify, python | +-------------------------------+----------+--------------------------------+ -| M2crypto or python-ssl (note | Any | python, openssl | -| that the ssl module is | | | -| included in python versions | | | -| 2.6 and later | | | +| python-ssl (note | Any | python, backported ssl module | ++-------------------------------+----------+--------------------------------+ +| python-setuptools | Any | | ++-------------------------------+----------+--------------------------------+ +| python-genshi | Any | | ++-------------------------------+----------+--------------------------------+ + +Bcfg2 Reporting +--------------- + +A webserver capabable of running wsgi applications is required for web +reporting, such as Apache + mod_wsgi or nginx. + ++-------------------------------+----------+--------------------------------+ +| Software | Version | Requires | ++===============================+==========+================================+ +| django | 1.2.0+ | | ++-------------------------------+----------+--------------------------------+ +| south | 0.7.5+ | | +-------------------------------+----------+--------------------------------+ Bcfg2 Reporting diff --git a/doc/installation/source.txt b/doc/installation/source.txt index 1406a5ceb..9bf023fbc 100644 --- a/doc/installation/source.txt +++ b/doc/installation/source.txt @@ -1,8 +1,9 @@ .. -*- mode: rst -*- +.. vim: ft=rst -.. _GPG1: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x75BF2C177F7D197E -.. _GPG2: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x80B8492FA88FFF4B -.. _Download: http://trac.mcs.anl.gov/projects/bcfg2/wiki/Download +.. _7F7D197E: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x75BF2C177F7D197E +.. _A88FFF4B: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x80B8492FA88FFF4B +.. _Download: http://bcfg2.org/download/ .. _source: @@ -17,8 +18,8 @@ Tarball The Bcfg2 source tarball can be grabbed from the `Download`_ page. -All tarballs are signed with GPG keys `7F7D197E <GPG1>`_ or `A88FFF4B -<GPG2>`_. You can verify your download by importing the keys and running :: +All tarballs are signed with GPG keys `7F7D197E`_ or `A88FFF4B`_. 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 diff --git a/doc/man/bcfg2-server.txt b/doc/man/bcfg2-server.txt index 3f8f3ea21..33d0df6cf 100644 --- a/doc/man/bcfg2-server.txt +++ b/doc/man/bcfg2-server.txt @@ -11,7 +11,7 @@ Synopsis **bcfg2-server** [-d] [-v] [-C *configfile*] [-D *pidfile*] [-E *encoding*] [-Q *repo path*] [-S *server url*] [-o *logfile*] [-x -*password*] [--ssl-key=\ *ssl key*] +*password*] [--ssl-key=\ *ssl key*] [--no-fam-blocking] Description ----------- @@ -22,19 +22,20 @@ configurations to clients based on the data in its repository. Options ------- --C configfile Specify alternate bcfg2.conf location. --D pidfile Daemonize, placing the program pid in *pidfile*. --E encoding Specify the encoding of config files. --Q path Specify the path to the server repository. --S server Manually specify the server location (as opposed to - using the value in bcfg2.conf). This should be in - the format "https://server:port" --d Enable debugging output. --v Run in verbose mode. --h Print usage information. ---ssl-key=key Specify the path to the SSL key. +-C configfile Specify alternate bcfg2.conf location. +-D pidfile Daemonize, placing the program pid in *pidfile*. +-E encoding Specify the encoding of config files. +-Q path Specify the path to the server repository. +-S server Manually specify the server location (as opposed to + using the value in bcfg2.conf). This should be in + the format "https://server:port" +-d Enable debugging output. +-v Run in verbose mode. +-h Print usage information. +--ssl-key=key Specify the path to the SSL key. +--no-fam-blocking Synonym for fam_blocking = False in bcfg2.conf See Also -------- -:manpage:`bcfg2(1)`, :manpage:`bcfg2-lint(8)` +:manpage:`bcfg2(1)`, :manpage:`bcfg2-lint(8)`, :manpage:`bcfg2.conf(5)` diff --git a/doc/man/bcfg2.conf.txt b/doc/man/bcfg2.conf.txt index df49f3d4a..825ab2121 100644 --- a/doc/man/bcfg2.conf.txt +++ b/doc/man/bcfg2.conf.txt @@ -49,7 +49,7 @@ fam_blocking Whether the server should block at startup until the file monitor backend has processed all events. This can cause a slower startup, but ensure that all files are recognized before the first client - is handled. + is handled. Defaults to True. ignore_files A comma-separated list of globs that should be ignored by the file @@ -447,7 +447,7 @@ settings used for client-server communication. sets the password to use to connect to the server. protocol - Communication protocol to use. Defaults to xmlrpc/ssl. + Communication protocol to use. Defaults to xmlrpc/tlsv1. retries A client-only option. Number of times to retry network @@ -537,6 +537,10 @@ Packages options The following options are specified in the **[packages]** section. + backends + Comma separated list of backends for the dependency resolution. + Default is "Yum,Apt,Pac,Pkgng". + resolver Enable dependency resolution. Default is 1 (true). @@ -632,7 +636,7 @@ Server-only, specified in the **[database]** section. These options control the database connection of the server. engine - The database engine used by the statistics module. One of the + The database engine used by server plugins. One of the following:: postgresql @@ -641,9 +645,9 @@ control the database connection of the server. ado_mssql name - The name of the database to use for statistics data. If + The name of the database to use for server data. If 'database_engine' is set to 'sqlite3' this is a file path to - the sqlite file and defaults to ``$REPOSITORY_DIR/etc/brpt.sqlite``. + the sqlite file and defaults to ``$REPOSITORY_DIR/etc/bcfg2.sqlite``. user User for database connections. Not used for sqlite3. @@ -662,6 +666,41 @@ control the database connection of the server. expected as multiple key=value pairs, separated with commas. The concrete value depends on the database engine. + reporting_engine + The database engine used by the Reporting plugin. One of the + following:: + + postgresql + mysql + sqlite3 + ado_mssql + + If reporting_engine is not specified, the Reporting plugin uses + the same database as the other server plugins. + + reporting_name + The name of the database to use for reporting data. If + 'database_engine' is set to 'sqlite3' this is a file path to + the sqlite file and defaults to + ``$REPOSITORY_DIR/etc/reporting.sqlite``. + + reporting_user + User for reporting database connections. Not used for sqlite3. + + reporting_password + Password for reporting database connections. Not used for sqlite3. + + reporting_host + Host for reporting database connections. Not used for sqlite3. + + reporting_port + Port for reporting database connections. Not used for sqlite3. + + reporting_options + Various options for the reporting database connection. The value + is expected as multiple key=value pairs, separated with commas. + The concrete value depends on the database engine. + Reporting options ----------------- diff --git a/doc/releases/1.3.4.txt b/doc/releases/1.3.4.txt new file mode 100644 index 000000000..f6bc13436 --- /dev/null +++ b/doc/releases/1.3.4.txt @@ -0,0 +1,49 @@ +.. -*- mode: rst -*- +.. vim: ft=rst + +.. _releases-1.3.4: + +1.3.4 +===== + +We are happy to announce the release of Bcfg2 1.3.4. It is available for +download at: + + ftp://ftp.mcs.anl.gov/pub/bcfg + +This is primarily a bugfix release. + +* New probes.allowed_groups option to restrict group assignments + +* Bundler fixes: + + * Fix parsing XML template output with encoding declaration + +* bcfg2-lint: + + * Resolve XIncludes when parsing XML for validation + * New TemplateAbuse plugin to detect templated scripts + * New ValidateJSON plugin + +* bcfg2-crypt fixes: + + * Fix logic + * Improve debugging/error handling with Properties files + * Fix exception handling + * Handle error when encrypting properties with multiple keys + +* Add new Augeas client tool driver: + http://docs.bcfg2.org/client/tools/augeas.html +* Restored bcfg2-admin client add functionality +* Migration tool fixes +* Schema fixes +* Add Django 1.6 support +* Use 'public' default pgsql database schema +* Refresh essential packages during Packages.Refresh +* Allow lxml.etree XML implementation to parse very large documents +* Support ACLs without a specific user/group +* Explicitly close database connections at the end of each client run +* Fix verification of symlinks + +Special thanks to the following contributors for this release: Matt Baker, +Simon Ruderich, Michael Fenn, Dan Foster, Richard Connon, John Morris. diff --git a/doc/releases/1.4.0pre1.txt b/doc/releases/1.4.0pre1.txt new file mode 100644 index 000000000..779873f41 --- /dev/null +++ b/doc/releases/1.4.0pre1.txt @@ -0,0 +1,182 @@ +.. -*- mode: rst -*- +.. vim: ft=rst + +.. _releases-1.4.0pre1: + +1.4.0pre1 +========= + +The first prerelease for Bcfg2 1.4.0 is now available at: + + ftp://ftp.mcs.anl.gov/pub/bcfg + +Bcfg2 1.4.0pre1 is a prerelease, and contains many new features, +including some that are backwards-incompatible with Bcfg2 1.3.x and +earlier. Please read the release notes thoroughly. This is a prerelease +and as such is not likely suitable for general production deployment. +That said, please help us test the release in non- and preproduction +environments. + +backwards-incompatible user-facing changes +------------------------------------------ + +* Completely rewrote option parser + + Many single character options now have long equivalents. Some + subcommand interfaces (``bcfg2-info``, ``bcfg2-admin``) have been + reorganized to some degree. ``bcfg2-reports`` syntax is completely + different. + +* Added new :ref:`server-plugins-misc-acl` plugin + + Default ACLs only allow clients to perform bcfg2 client runs, and only + permit `bcfg2-admin xcmd` calls from localhost. If you want to change + this, you must enable the ACL plugin and configure your own ACLs. + +* Added genshi requirement for the server + +* :ref:`server-plugins-generators-decisions` + + * Switch plugin to use StructFile instead of host- or group-specific XML + files (this allows a single e.g. whitelist.xml file with <Group> tags) + + You can convert your existing decisions using + ``tools/upgrade/1.4/migrate_decisions.py``. + + +deprecated features (will be removed in a future release, likely 1.5) +--------------------------------------------------------------------- + +* :ref:`server-plugins-structures-bundler` + + * Deprecated use of an explicit name attribute + + You can convert your existing bundles using + ``tools/upgrade/1.4/convert_bundles.py``. + + * Deprecated :ref:`.genshi bundles + <server-plugins-structures-bundler-index-genshi-templates>` (use + .xml bundles and specify the genshi namespace instead) + +* SSLCA + + * Deprecated plugin + * SSLCA functionality has been added to the Cfg plugin: + see :ref:`server-plugins-generators-cfg-ssl-certificates` + +deprecated plugins and features which have been removed +------------------------------------------------------- + +Plugins +^^^^^^^ + +* PostInstall +* TGenshi +* TCheetah +* Account +* Hostbase +* Snapshots +* Statistics +* Editor +* Base + +Client tools +^^^^^^^^^^^^ + +* RPMng +* YUM24 +* YUMng + +Other features +^^^^^^^^^^^^^^ + +* FAM filemonitor +* Removed mode="inherit" support +* Removed support for .cat/.diff files +* Removed support for info/:info files +* Removed "magic" groups (for the Packages plugin) + +other fixes and new features +---------------------------- + +* Added :ref:`inter-bundle dependencies + <server-plugins-structures-bundler-index-dependencies>` +* Added support for :ref:`independent bundles + <server-plugins-structures-bundler-index-disabling-magic>` (replaces + the functionality of Base): +* Added support for wildcard XIncludes +* Add Solaris 11 IPS Package support +* Add bcfg2-report-collector init script to debian package +* Git VCS plugin enhancements +* Removed deprecated plugins + +* :ref:`server-plugins-structures-bundler` + + * Deprecated use of an explicit name attribute + * Deprecated .genshi bundles + * Added path globbing + +* :ref:`server-plugins-grouping-metadata` + + * Allow setting global default authentication type + +* :ref:`server-plugins-generators-packages` + + * Add yum group support to internal resolver + * Change location of plugin-generated APT sources + * Add new Pkgng plugin + * Add ability for per-package recommended flag override + +* :ref:`server-plugins-statistics-reporting` + + * Add support for POSIX user/group entries + * Add support for Django > 1.4 + * Add support for separate reporting database + +* Added option to periodically dump performance stats to logs +* Added option to force server to wait until all FAM events are + processed + +* :ref:`server-plugins-generators-sshbase` + + * Add support for IPv6 addresses in known_hosts file + * Add support for :ref:`encryption of generated ssh keys + <server-plugins-generators-sshbase-encryption>` + +* APT + + * Allow specification of deb-src lines (resolves + http://trac.mcs.anl.gov/projects/bcfg2/ticket/1148) + +* SSLCA + + * Rewrote SSLCA as Cfg handler + + Existing SSLCA installations will need to migrate to the new format + using ``tools/upgrade/1.4/migrate_sslca.py``. + +* :ref:`server-plugins-generators-nagiosgen` + + * Migrate configuration to conf.d + +* :ref:`server-plugins-probes` + + * Rewritten to improve caching + * Add probes.allowed_groups option to restrict group assignments: + see :ref:`server-plugins-probes-dynamic-groups` + + +Thanks +------ + +Special thanks to the following contributors for this release + + * Alexander Sulfrain + * Chris Brinker + * Duncan Hutty + * Jason Kincl + * John Morris + * Matt Schwager + * Michael Fenn + * Stéphane Graber + * Tim Laszlo diff --git a/doc/releases/1.4.0pre2.txt b/doc/releases/1.4.0pre2.txt new file mode 100644 index 000000000..7bbed5603 --- /dev/null +++ b/doc/releases/1.4.0pre2.txt @@ -0,0 +1,37 @@ +.. -*- mode: rst -*- +.. vim: ft=rst + +.. _releases-1.4.0pre2: + +1.4.0pre2 +========= + +The second prerelease for Bcfg2 1.4.0 is now available at: + + ftp://ftp.mcs.anl.gov/pub/bcfg + +Bcfg2 1.4.0pre2 is a prerelease, and contains many new features, +including some that are backwards-incompatible with Bcfg2 1.3.x and +earlier. Please read the release notes thoroughly. This is a prerelease +and as such is not likely suitable for general production deployment. +That said, please help us test the release in non- and preproduction +environments. + +backwards-incompatible user-facing changes +------------------------------------------ + +* Changed default communication protocol to xmlrpc/tlsv1 + +* Diff output from files sent to the Reports plugin from the client will now be + in a unified diff format rather than the previous n-diff format. + + This fixes potentially long client runs when comparing files that have + diverged significantly. + +Thanks +------ + +Special thanks to the following contributors for this release + + * Alexander Sulfrain + * Matt Kemp diff --git a/doc/releases/index.txt b/doc/releases/index.txt new file mode 100644 index 000000000..479aa19de --- /dev/null +++ b/doc/releases/index.txt @@ -0,0 +1,13 @@ +.. -*- mode: rst -*- +.. vim: ft=rst + +.. _releases-index: + +===================== +Release Announcements +===================== + +.. toctree:: + + 1.4.0pre1 + 1.3.4 diff --git a/doc/reports/dynamic.txt b/doc/reports/dynamic.txt index 6b8a1f467..53bdef24e 100644 --- a/doc/reports/dynamic.txt +++ b/doc/reports/dynamic.txt @@ -25,6 +25,7 @@ configuration. Specific features in the new system include: users to drill down to find out about a :ref:`specific host <reports-client-detail>`, rather than only having one huge page with too much information. +* Ability to store reporting data separately from other server data. Installation ============ @@ -214,8 +215,8 @@ database ^^^^^^^^ If you choose to use a different database, you'll need to edit -``/etc/bcfg2.conf``. These fields should be updated in the [database] -section: +``/etc/bcfg2.conf``. These fields should be updated in the +``[database]`` section: * engine @@ -228,11 +229,27 @@ section: * host * port (optional) +To store reporting data separately from the main server data, use +the following options: + +* reporting_engine + + * ex: reporting_engine = mysql + * ex: reporting_engine = postgresql_psycopg2 + +* reporting_name +* reporting_user +* reporting_password +* reporting_host +* reporting_port (optional) + .. warning:: If mysql is used as a backend, it is recommended to use InnoDB for the `storage engine <http://dev.mysql.com/doc/refman/5.1/en/storage-engine-setting.html>`_. +Refer to :ref:`server-database` for a full listing of +available options. statistics ^^^^^^^^^^ diff --git a/doc/server/caching.txt b/doc/server/caching.txt index 32be684db..3557bf0f3 100644 --- a/doc/server/caching.txt +++ b/doc/server/caching.txt @@ -1,4 +1,5 @@ .. -*- mode: rst -*- +.. vim: ft=rst .. _server-caching: @@ -42,15 +43,15 @@ descending order of reliability. That is, odds are higher that biggest speed boost. ``off`` will never result in stale data, but it gives no speed boost. -In addition to the :ref:`server-plugins-grouping-metadata` plugin, -Bcfg2 includes three plugins that can set additional groups, and thus -may affect the caching behavior. They are -:ref:`server-plugins-grouping-grouppatterns`, -:ref:`server-plugins-probes-index`, and +In addition to the :ref:`server-plugins-grouping-metadata` +plugin, Bcfg2 includes three plugins that can set additional +groups, and thus may affect the caching behavior. They +are :ref:`server-plugins-grouping-grouppatterns`, +:ref:`server-plugins-probes`, and :ref:`server-plugins-connectors-puppetenc`. All of those plugins -**except** for PuppetENC fully support all caching levels. PuppetENC -is incompatible with ``aggressive``, and may result in some stale data -with ``cautious``. +**except** for PuppetENC fully support all caching levels. PuppetENC is +incompatible with ``aggressive``, and may result in some stale data with +``cautious``. If you are not using the PuppetENC plugin, and do not have any custom plugins that provide additional groups, then all four modes should be diff --git a/doc/server/configuration.txt b/doc/server/configuration.txt index d3fa42601..79d732f6d 100644 --- a/doc/server/configuration.txt +++ b/doc/server/configuration.txt @@ -216,3 +216,46 @@ To select which backend to use, set the ``backend`` option in the * ``best`` (the default; currently the same as ``builtin``) ``best`` may change in future releases. + +Multiprocessing core configuration +---------------------------------- + +If you use the multiprocessing core, there are other bits you may wish +to twiddle. + +By default, the server spawns as many children as the host has CPUs. +(This is determined by ``multiprocessing.cpu_count()``.) To change +this, set: + +.. code-block:: ini + + [server] + children = 4 + +The optimal number of children may vary depending on your workload. +For instance, if you are using :ref:`native yum +library support <native-yum-libraries>`, then a separate process is +spawned for each client to resolve its package dependencies, so +keeping the children at or below the CPU count is likely a good idea. +If you're not using native yum library support, though, you may wish +to oversubscribe the core slightly. It's recommended that you test +various configurations and use what works best for your workload. + +Secondly, if ``tmpwatch`` is enabled, you must either disable it or +exclude the pattern ``/tmp/pymp-\*``. For instance, on RHEL or CentOS +you may have a line like the following in +``/etc/cron.daily/tmpwatch``: + +.. code-block:: bash + + /usr/sbin/tmpwatch -x /tmp/.X11-unix -x /tmp/.XIM-unix -x /tmp/.font-unix \ + -x /tmp/.ICE-unix -x /tmp/.Test-unix 240 /tmp + +You would need to add ``-X /tmp/pymp-\*`` to it, like so: + +.. code-block:: bash + + /usr/sbin/tmpwatch -x /tmp/.X11-unix -x /tmp/.XIM-unix -x /tmp/.font-unix \ + -x /tmp/.ICE-unix -x /tmp/.Test-unix -X /tmp/pymp-\* 240 /tmp + +See https://bugzilla.redhat.com/show_bug.cgi?id=1058310 for more information. diff --git a/doc/server/database.txt b/doc/server/database.txt index 3c8970f68..986914171 100644 --- a/doc/server/database.txt +++ b/doc/server/database.txt @@ -1,4 +1,5 @@ .. -*- mode: rst -*- +.. vim: ft=rst .. _server-database: @@ -9,51 +10,86 @@ Global Database Settings .. versionadded:: 1.3.0 Several Bcfg2 plugins, including -:ref:`server-plugins-grouping-metadata`, -:ref:`server-plugins-probes-index`, and -:ref:`server-plugins-statistics-reporting`, can connect use a -relational database to store data. They use the global database -settings in ``bcfg2.conf``, described in this document, to connect. +:ref:`server-plugins-grouping-metadata`, :ref:`server-plugins-probes`, and +:ref:`server-plugins-statistics-reporting`, can connect use a relational +database to store data. They use the global database settings in +``bcfg2.conf``, described in this document, to connect. .. note:: Although SQLite is supported as a database, it may cause - significant thread contention (and a performance penalty) if you - use SQLite with :ref:`server-plugins-grouping-metadata` or - :ref:`server-plugins-probes-index`. If you are using the - database-backed features of either of those plugins, it's - recommended that you use a higher performance database backend. + significant thread contention (and a performance penalty) if + you use SQLite with :ref:`server-plugins-grouping-metadata` or + :ref:`server-plugins-probes`. If you are using the database-backed + features of either of those plugins, it's recommended that you use + a higher performance database backend. +Separate Reporting Database +=========================== + +.. versionadded:: 1.4.0 + +Bcfg2 supports storing the data generated by the +:ref:`server-plugins-statistics-reporting` in a separate +database from the data generated by the other plugins (e.g. +:ref:`server-plugins-grouping-metadata` and :ref:`server-plugins-probes`). +To activate this support, set the ``reporting_engine``, +``reporting_name``, ``reporting_user``, etc. options in the +``[database]`` section of the config file. The valid values for the +``reporting_*`` options are the same as for the standard database +options. See :ref:`server-database-configuration-options` for a full +listing. + +.. _server-database-configuration-options: + Configuration Options ===================== All of the following options should go in the ``[database]`` section of ``/etc/bcfg2.conf``. -+-------------+------------------------------------------------------------+-------------------------------+ -| Option name | Description | Default | -+=============+============================================================+===============================+ -| engine | The name of the Django database backend to use. See | "sqlite3" | -| | https://docs.djangoproject.com/en/dev/ref/settings/#engine | | -| | for available options (note that django.db.backends is not | | -| | included in the engine name) | | -+-------------+------------------------------------------------------------+-------------------------------+ -| name | The name of the database | "/var/lib/bcfg2/bcfg2.sqlite" | -+-------------+------------------------------------------------------------+-------------------------------+ -| user | The user to connect to the database as | None | -+-------------+------------------------------------------------------------+-------------------------------+ -| password | The password to connect to the database with | None | -+-------------+------------------------------------------------------------+-------------------------------+ -| host | The host to connect to | "localhost" | -+-------------+------------------------------------------------------------+-------------------------------+ -| port | The port to connect to | None | -+-------------+------------------------------------------------------------+-------------------------------+ -| options | Extra parameters to use when connecting to the database. | None | -| | Available parameters vary depending on your database | | -| | backend. The parameters are supplied as comma separated | | -| | key=value pairs. | | -+-------------+------------------------------------------------------------+-------------------------------+ ++--------------------+------------------------------------------------------------+---------------------------------------+ +| Option name | Description | Default | ++====================+============================================================+=======================================+ +| engine | The name of the Django database backend to use. See | "sqlite3" | +| | https://docs.djangoproject.com/en/dev/ref/settings/#engine | | +| | for available options (note that django.db.backends is not | | +| | included in the engine name) | | ++--------------------+------------------------------------------------------------+---------------------------------------+ +| name | The name of the database | "/var/lib/bcfg2/etc/bcfg2.sqlite" | ++--------------------+------------------------------------------------------------+---------------------------------------+ +| user | The user to connect to the database as | None | ++--------------------+------------------------------------------------------------+---------------------------------------+ +| password | The password to connect to the database with | None | ++--------------------+------------------------------------------------------------+---------------------------------------+ +| host | The host to connect to | "localhost" | ++--------------------+------------------------------------------------------------+---------------------------------------+ +| port | The port to connect to | None | ++--------------------+------------------------------------------------------------+---------------------------------------+ +| options | Extra parameters to use when connecting to the database. | None | +| | Available parameters vary depending on your database | | +| | backend. The parameters are supplied as comma separated | | +| | key=value pairs. | | ++--------------------+------------------------------------------------------------+---------------------------------------+ +| reporting_engine | The name of the Django database backend to use for the | None | +| | reporting database. Takes the same values as ``engine``. | | ++--------------------+------------------------------------------------------------+---------------------------------------+ +| reporting_name | The name of the reporting database | "/var/lib/bcfg2/etc/reporting.sqlite" | ++--------------------+------------------------------------------------------------+---------------------------------------+ +| reporting_user | The user to connect to the reporting database as | None | ++--------------------+------------------------------------------------------------+---------------------------------------+ +| reporting_password | The password to connect to the reporting database with | None | ++--------------------+------------------------------------------------------------+---------------------------------------+ +| reporting_host | The host to connect to for the reporting database | "localhost" | ++--------------------+------------------------------------------------------------+---------------------------------------+ +| reporting_port | The port to connect to for the reporting database | None | ++--------------------+------------------------------------------------------------+---------------------------------------+ +| reporting_options | Extra parameters to use when connecting to the reporting | None | +| | database. Available parameters vary depending on your | | +| | database backend. The parameters are supplied as comma | | +| | separated key=value pairs. | | ++--------------------+------------------------------------------------------------+---------------------------------------+ Database Schema Sync diff --git a/doc/server/encryption.txt b/doc/server/encryption.txt index b657deb8c..db5e2ae29 100644 --- a/doc/server/encryption.txt +++ b/doc/server/encryption.txt @@ -1,4 +1,5 @@ .. -*- mode: rst -*- +.. vim: ft=rst .. _server-encryption: @@ -54,7 +55,7 @@ In general, Properties encryption is preferred for a few reasons: Other types of data that can be encrypted are: * Text content of Path tags in - :ref:`server-plugins-structures-bundler-index` + :ref:`server-plugins-structures-bundler` * Passphrases in XML description files for generated :ref:`server-plugins-generators-cfg-sshkeys` diff --git a/doc/server/plugins/generators/cfg.txt b/doc/server/plugins/generators/cfg.txt index 7a404c824..8b49e244b 100644 --- a/doc/server/plugins/generators/cfg.txt +++ b/doc/server/plugins/generators/cfg.txt @@ -1,4 +1,5 @@ .. -*- mode: rst -*- +.. vim: ft=rst .. _server-plugins-generators-cfg: @@ -29,8 +30,8 @@ in ``Cfg/etc/passwd/passwd``, while the ssh pam module config file, ``/etc/pam.d/sshd``, goes in ``Cfg/etc/pam.d/sshd/sshd``. The reason for the like-name directory is to allow multiple versions of each file to exist, as described below. Note that these files are exact copies of what -will appear on the client machine (except when using Genshi or Cheetah -templating -- see below). +will appear on the client machine (except when using templates -- see +below). Group-Specific Files ==================== @@ -241,6 +242,27 @@ comment to appear in the final config file.:: # This is a comment in my template which will be stripped when it's processed through Cheetah \# This comment will appear in the generated config file. +.. _server-plugins-generators-cfg-jinja2: + +Jinja2 Templates +----------------- + +Jinja2 templates allow you to use the `jinja2 templating system +<http://jinja.pocoo.org/>`_. Jinja2 templates should be +named with a ``.jinja2`` extension, e.g.:: + + % ls Cfg/etc/motd + info.xml motd.jinja2 + +Examples +~~~~~~~~ + +.. toctree:: + :glob: + :maxdepth: 1 + + examples/jinja2/* + Inside Templates ---------------- @@ -262,10 +284,10 @@ Several variables are pre-defined inside templates: | repo | The path to the Bcfg2 repository on the filesystem | +-------------+--------------------------------------------------------+ | path | In Genshi templates, ``path`` is a synonym for | -| | ``source_path``. In Cheetah templates, it's a synonym | -| | for ``name``. For this reason, use of ``path`` is | -| | discouraged, and it may be deprecated in a future | -| | release. | +| | ``source_path``. In Cheetah templates and Jinja2 | +| | templates, it's a synonym for ``name``. For this | +| | reason, use of ``path`` is discouraged, and it may be | +| | deprecated in a future release. | +-------------+--------------------------------------------------------+ To access these variables in a Genshi template, you can simply use the @@ -273,6 +295,10 @@ name, e.g.:: Path to this file: ${name} +Similarly, in a Jinja2 template:: + + Path to this file: {{ name }} + In a Cheetah template, the variables are properties of ``self``, e.g.:: @@ -282,15 +308,15 @@ Notes on Using Templates ------------------------ Templates can be host and group specific as well. Deltas will not be -processed for any Genshi or Cheetah base file. +processed for any Genshi, Cheetah, or Jinja2 base file. .. note:: If you are using templating in combination with host-specific or group-specific files, you will need to ensure that the ``.genshi`` - or ``.cheetah`` extension is at the **end** of the filename. Using the - examples from above for *host.example.com* and group *server* you would - have the following:: + ``.cheetah`` or ``.jinja2`` extension is at the **end** of the filename. + Using the examples from above for *host.example.com* and group *server* + you would have the following:: Cfg/etc/fstab/fstab.H_host.example.com.genshi Cfg/etc/fstab/fstab.G50_server.cheetah @@ -344,7 +370,7 @@ An encrypted file should end with ``.crypt``, e.g.:: Cfg/etc/foo.conf/foo.conf.crypt Cfg/etc/foo.conf/foo.conf.G10_foo.crypt -Encrypted Genshi or Cheetah templates can have the extensions in +Encrypted Genshi, Cheetah, and Jinja2 templates can have the extensions in either order, e.g.:: Cfg/etc/foo.conf/foo.conf.crypt.genshi diff --git a/doc/server/plugins/generators/examples/jinja2/simple.txt b/doc/server/plugins/generators/examples/jinja2/simple.txt new file mode 100644 index 000000000..b4ab844fb --- /dev/null +++ b/doc/server/plugins/generators/examples/jinja2/simple.txt @@ -0,0 +1,53 @@ +.. -*- mode: rst -*- + +========================= + Basic Jinja2 Templates +========================= + +This simple example demonstrates basic usage of Jinja2 templates. + +``/var/lib/bcfg2/Cfg/foo/foo.jinja2`` + +.. code-block:: none + + Hostname is {{ metadata.hostname }} + Filename is {{ name }} + Template is {{ source_path }} + Groups: + {% for group in metadata.groups -%} + * {{ group }} + {% endfor %} + Categories: + {% for category in metadata.categories -%} + * {{ category }} -- {{ metadata.categories[category] }} + {% endfor %} + + Probes: + {% for probe in metadata.Probes -%} + * {{ probe }} -- {{ metadata.Probes[probe] }} + {% endfor %} + +Output +====== + +.. code-block:: xml + + <Path type="file" name="/foo" owner="root" mode="0644" group="root"> + Hostname is topaz.mcs.anl.gov + Filename is /foo + Template is /var/lib/bcfg2/Cfg/foo/foo.jinja2 + Groups: + * desktop + * mcs-base + * ypbound + * workstation + * xserver + * debian-sarge + * debian + * a + Categories: + * test -- a + + Probes: + * os -- debian + </Path> diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt index 8b317552f..2fe71f895 100644 --- a/doc/server/plugins/generators/packages.txt +++ b/doc/server/plugins/generators/packages.txt @@ -217,10 +217,6 @@ something like this: <Source type="apt" recommended="true" ...> - .. warning:: You must regenerate the Packages cache when adding or - removing the recommended attribute (``bcfg2-admin xcmd - Packages.Refresh``). - .. [#f1] Bcfg2 will by default add **Essential** packages to the client specification. You can disable this behavior by setting the :xml:attribute:`SourceType:essential` @@ -347,9 +343,85 @@ This is done automatically any time `sources.xml`_ is updated. Availability ============ -Support for clients using yum and apt is currently available. Support for +Support for the following clients is currently available. Support for other package managers (Portage, Zypper, IPS, etc) remain to be added. +apt +--- + +All dpkg based clients (for example Debian, Ubuntu or Nexenta) could be +handled with the apt module: + +.. code-block:: xml + + <Source type="apt" + url="http://us.archive.ubuntu.com/ubuntu" + version="intrepid"> + <Component>main</Component> + <Component>universe</Component> + <Arch>i386</Arch> + <Arch>amd64</Arch> + </Source> + + +pac +--- + +For Arch Linux or Parabola GNU/Linux-libre you could use the pac module +for packages. You do not need to supply a version attribute as the mirrors +are rolling release and does not supply different versions. + +.. code-block:: xml + + <Source type="pac" + url="http://mirrors.kernel.org/archlinux/"> + <Component>core</Component> + <Component>extra</Component> + <Component>community</Component> + <Arch>i686</Arch> + <Arch>x86_64</Arch> + </Source> + + +pkgng +----- + +The support for the Next Generation package management tool for FreeBSD +is called pkgng. It downloads the packagesite file from the mirror +and parses the dependencies out of it. It currently does not use the +DNS SRV record lookup mechanism to get the correct mirror and does +not verify the signature inside the packagesite file. + +.. code-block:: xml + + <Source type="pkgng" + url="http://pkg.freebsd.org/" + version="10"> + <Component>latest</Component> + <Arch>x86:64</Arch> + <Arch>x86:32</Arch> + </Source> + + +yum +--- + +Rpm based clients (for example RedHat, CentOS or Fedora) could be handled +with the yum module: + +.. code-block:: xml + + <Source type="yum" + url="http://mirror.centos.org/centos/" + version="5.2"> + <Component>os</Component> + <Component>updates</Component> + <Component>extras</Component> + <Arch>i386</Arch> + <Arch>x86_64</Arch> + </Source> + + Package Checking and Verification ================================= @@ -645,6 +717,9 @@ It understands the following directives: +-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ | Name | Description | Values | Default | +=============+======================================================+==========+===================================================================+ +| backends | List of backends that should be loaded for the | List | Yum,Apt,Pac,Pkgng | +| | dependency resolution. | | | ++-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ | resolver | Enable dependency resolution | Boolean | True | +-------------+------------------------------------------------------+----------+-------------------------------------------------------------------+ | metadata | Enable metadata processing. Disabling ``metadata`` | Boolean | True | diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt index 64dbc8597..86478a5ae 100644 --- a/doc/server/plugins/generators/rules.txt +++ b/doc/server/plugins/generators/rules.txt @@ -118,6 +118,20 @@ Attributes common to all Path tags: :onlyattrs: name,type +augeas +^^^^^^ + +Run `Augeas <http://www.augeas.net>`_ commands. See +:ref:`client-tools-augeas` for more details. + +.. xml:type:: PathType + :nochildren: + :noattributegroups: + :nodoc: + :notext: + :onlyattrs: owner,group,mode,secontext,lens + :requiredattrs: owner,group,mode + device ^^^^^^ @@ -263,6 +277,7 @@ child ``<ACL>`` tags. For instance: mode="0775"> <ACL type="default" scope="user" user="foouser" perms="rw"/> <ACL type="default" scope="group" group="users" perms="rx"/> + <ACL type="default" scope="other" perms="r"/> </Path> .. xml:element:: ACL @@ -271,6 +286,9 @@ It is not currently possible to manually set an effective rights mask; the mask will be automatically calculated from the given ACLs when they are applied. +For directories either no default ACL entries or at least an entry for +the owner, owning group and other must be defined. + Note that it is possible to set ACLs that demand different permissions on a file than those specified in the ``perms`` attribute on the ``Path`` tag. For instance: diff --git a/doc/server/plugins/generators/sshbase.txt b/doc/server/plugins/generators/sshbase.txt index 641b9c598..540cc1e06 100644 --- a/doc/server/plugins/generators/sshbase.txt +++ b/doc/server/plugins/generators/sshbase.txt @@ -1,4 +1,5 @@ .. -*- mode: rst -*- +.. vim: ft=rst .. _server-plugins-generators-sshbase: @@ -13,8 +14,9 @@ record for the current system. It has two functions: -* Generating new ssh keys -- When a client requests a dsa, rsa, or v1 key, - and there is no existing key in the repository, one is generated. +* Generating new ssh keys -- When a client requests a ecdsa, dsa, rsa, + or v1 key, and there is no existing key in the repository, one is + generated. * Maintaining the ``ssh_known_hosts`` file -- all current known public keys (and extra public key stores) are integrated into a single @@ -31,7 +33,7 @@ Interacting with SSHbase ``<repo>/SSHbase/<key filename>.H_<hostname>`` * Pre-seeding can also be performed using ``bcfg2-admin pull - ConfigFile /name/of/ssh/key`` + Path /name/of/ssh/key`` * Revoking existing keys -- deleting ``<repo>/SSHbase/\*.H_<hostname>`` will remove keys for an existing @@ -160,6 +162,9 @@ in order to permit :ref:`pulling with bcfg2-admin <server-admin-pull>`. You should almost certainly set ``sensitive`` to "true" in ``info.xml``. + +.. _server-plugins-generators-sshbase-encryption: + Encryption ========== diff --git a/doc/server/plugins/index.txt b/doc/server/plugins/index.txt index f3d6daa73..b39be0786 100644 --- a/doc/server/plugins/index.txt +++ b/doc/server/plugins/index.txt @@ -1,4 +1,5 @@ .. -*- mode: rst -*- +.. vim: ft=rst .. _server-plugins-index: @@ -13,7 +14,7 @@ perform one of several tasks: #. Generating configuration entry contents for clients #. Probing client-side state (like hardware inventory, etc) -- the generic client probing mechanism is described at - :ref:`server-plugins-probes-index`. + :ref:`server-plugins-probes`. #. Automating administrative tasks (e.g. :ref:`server-plugins-generators-sshbase` which automates ssh key management) diff --git a/doc/server/plugins/probes/index.txt b/doc/server/plugins/probes/index.txt index 306a752b6..434ce20a8 100644 --- a/doc/server/plugins/probes/index.txt +++ b/doc/server/plugins/probes/index.txt @@ -1,6 +1,7 @@ .. -*- mode: rst -*- +.. vim: ft=rst -.. _server-plugins-probes-index: +.. _server-plugins-probes: ====== Probes @@ -13,6 +14,9 @@ the system disk, you would want to know this information to correctly generate an `/etc/auto.master` autofs config file for each type. Here we will look at how to do this. +Probes also allow dynamic group assignment for clients, see +:ref:`server-plugins-probes-dynamic-groups`. + First, create a ``Probes`` directory in our toplevel repository location:: @@ -119,6 +123,45 @@ is to add the ``/etc/auto.master`` to a Bundle: <Path name='/etc/auto.master'/> +.. _server-plugins-probes-dynamic-groups: + +Dynamic Group Assignment +======================== + +The output lines of the probe matching "group:" are used to +dynamically assign hosts to groups. These dynamic groups need not already +exist in ``Metadata/groups.xml``. If a dynamic group is defined in +``Metadata/groups.xml``, clients that include this group will also get +all included groups and bundles. + +Consider the following output of a probe:: + + group:debian-wheezy + group:amd64 + +This assigns the client to the groups debian-wheezy and amd64. + +To prevent clients from manipulating the probe output and choosing +unexpected groups (and receiving their potential sensitive files) you +can use the ``allowed_groups`` option in the ``[probes]`` section of +``bcfg2.conf`` on the server. This whitespace-separated list of +anchored regular expressions (must match the complete group name) +controls dynamic group assignments. Only matching groups are +allowed. The default allows all groups. + +.. versionadded:: 1.3.4 + +Example: + +.. code-block:: ini + + [probes] + allowed_groups = debian-(squeeze|wheezy|sid) i386 + +This allows the groups `debian-squeeze`, `debian-wheezy`, `debian-sid` +and `i386`. With the probe output from above, this setting would +disallow the group `amd64`. + Handling Probe Output ===================== diff --git a/doc/server/plugins/structures/bundler/index.txt b/doc/server/plugins/structures/bundler/index.txt index 0b6b8eb50..31faeaf17 100644 --- a/doc/server/plugins/structures/bundler/index.txt +++ b/doc/server/plugins/structures/bundler/index.txt @@ -1,6 +1,7 @@ .. -*- mode: rst -*- +.. vim: ft=rst -.. _server-plugins-structures-bundler-index: +.. _server-plugins-structures-bundler: ======= Bundler @@ -91,6 +92,9 @@ split these entries into two bundles. See :ref:`server-plugins-structures-bundler-bcfg2-server` for an example of this. + +.. _server-plugins-structures-bundler-index-disabling-magic: + Disabling Magic --------------- @@ -111,6 +115,9 @@ entries in independent bundles are only executed if ``when="always"``. (I.e., an Action entry in an independent bundle with ``when="modified"`` is useless.) + +.. _server-plugins-structures-bundler-index-genshi-templates: + Genshi templates ================ @@ -138,6 +145,9 @@ entries in the bundle. See :ref:`bcfg2-info <server-bcfg2-info>` for more details. + +.. _server-plugins-structures-bundler-index-dependencies: + Dependencies ============ diff --git a/doc/server/plugins/structures/bundler/nagios.txt b/doc/server/plugins/structures/bundler/nagios.txt index d25e1cf0a..47a61b898 100644 --- a/doc/server/plugins/structures/bundler/nagios.txt +++ b/doc/server/plugins/structures/bundler/nagios.txt @@ -27,29 +27,14 @@ the clients. <Path name='/etc/hosts.deny'/> <Path name='/etc/services'/> <Path name='/etc/snmpd.conf'/> - <Path name='/usr/lib/nagios/plugins/check_disks_scratchgpfs1.tg'/> - <Path name='/usr/lib/nagios/plugins/check_fs.mds'/> - <Path name='/usr/lib/nagios/plugins/check_gm_network.tg'/> - <Path name='/usr/lib/nagios/plugins/check_gpfs_wan.tg'/> - <Path name='/usr/lib/nagios/plugins/check_hung_jobs.tg'/> - <Path name='/usr/lib/nagios/plugins/check_mem.mds'/> - <Path name='/usr/lib/nagios/plugins/check_mem.tg'/> - <Path name='/usr/lib/nagios/plugins/check_nvidia_acceleration.tg'/> - <Path name='/usr/lib/nagios/plugins/check_os.mds'/> - <Path name='/usr/lib/nagios/plugins/check_procinfo.mds'/> - <Path name='/usr/lib/nagios/plugins/check_torque.tg'/> - <Path name='/usr/lib/nagios/plugins/check_uname_r.tg'/> - <Path name='/usr/lib/nagios/plugins/check_uname_r.tg.conf'/> + <Path glob='/usr/lib/nagios/plugins/*'/> <Service name='snmpd'/> <Group name='nagios-server'> <Package name='nagios'/> <Package name='nagios-devel'/> <Package name='nagios-www'/> <Path name='/etc/httpd/conf.d/nagios.conf'/> - <Path name='/etc/nagios/cgi.cfg'/> - <Path name='/etc/nagios/checkcommands.cfg'/> - <Path name='/etc/nagios/nagios.cfg'/> - <Path name='/etc/nagios/resource.cfg'/> + <Path glob='/etc/nagios/*'/> </Group> </Bundle> diff --git a/doc/server/plugins/structures/bundler/torque.txt b/doc/server/plugins/structures/bundler/torque.txt index f6349df6e..01316f3a3 100644 --- a/doc/server/plugins/structures/bundler/torque.txt +++ b/doc/server/plugins/structures/bundler/torque.txt @@ -29,9 +29,7 @@ A longer Bundle that includes many group-specific entries. <BoundPath type='directory' owner='root' group='root' mode='0755' name='/var/spool/torque/mom_logs'/> <BoundPath type='directory' owner='root' group='root' mode='0755' name='/var/spool/torque/mom_priv'/> <BoundPath type='directory' owner='root' group='root' mode='0755' name='/var/spool/torque/mom_priv/jobs'/> - <Path name='/var/spool/torque/mom_priv/config'/> - <Path name='/var/spool/torque/mom_priv/prologue'/> - <Path name='/var/spool/torque/mom_priv/epilogue'/> + <Path glob='/var/spool/torque/mom_priv/*'/> </Group> <Group name='torque-server'> <Service name='torque_server'/> diff --git a/doc/server/xml-common.txt b/doc/server/xml-common.txt index 3aacfd468..5302a59e4 100644 --- a/doc/server/xml-common.txt +++ b/doc/server/xml-common.txt @@ -1,4 +1,5 @@ .. -*- mode: rst -*- +.. vim: ft=rst .. _xml-features: @@ -76,20 +77,12 @@ Or, more compactly: Manage the abstract service "bar" As an example, consider the following :ref:`bundle -<server-plugins-structures-bundler-index>`: +<server-plugins-structures-bundler>`: .. code-block:: xml <Bundle> - <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'/> - <Path name='/etc/ssh/ssh_host_rsa_key.pub'/> - <Path name='/etc/ssh/ssh_host_key'/> - <Path name='/etc/ssh/ssh_host_key.pub'/> - <Path name='/etc/ssh/sshd_config'/> - <Path name='/etc/ssh/ssh_config'/> - <Path name='/etc/ssh/ssh_known_hosts'/> + <Path glob='/etc/ssh/*'/> <Group name='rpm'> <Package name='openssh'/> <Package name='openssh-askpass'/> @@ -122,23 +115,7 @@ any other clients. +------------------------+-----------------------------------+ | Group/Hostname | Entry | +========================+===================================+ -| all | ``/etc/ssh/ssh_host_dsa_key`` | -+------------------------+-----------------------------------+ -| all | ``/etc/ssh/ssh_host_rsa_key`` | -+------------------------+-----------------------------------+ -| all | ``/etc/ssh/ssh_host_dsa_key.pub`` | -+------------------------+-----------------------------------+ -| all | ``/etc/ssh/ssh_host_rsa_key.pub`` | -+------------------------+-----------------------------------+ -| all | ``/etc/ssh/ssh_host_key`` | -+------------------------+-----------------------------------+ -| all | ``/etc/ssh/ssh_host_key.pub`` | -+------------------------+-----------------------------------+ -| all | ``/etc/ssh/sshd_config`` | -+------------------------+-----------------------------------+ -| all | ``/etc/ssh/ssh_config`` | -+------------------------+-----------------------------------+ -| all | ``/etc/ssh/ssh_known_hosts`` | +| all | ``/etc/ssh/*`` | +------------------------+-----------------------------------+ | ``rpm`` | Package ``openssh`` | +------------------------+-----------------------------------+ @@ -333,7 +310,7 @@ Feature Matrix | <server-plugins-misc-acl>` | | | | | +---------------------------------------------------+--------------+--------+------------+------------+ | :ref:`Bundler | Yes | Yes | Yes | Yes | -| <server-plugins-structures-bundler-index>` | | | | | +| <server-plugins-structures-bundler>` | | | | | +---------------------------------------------------+--------------+--------+------------+------------+ | :ref:`info.xml <server-info>` | Yes [#f1]_ | Yes | Yes | Yes | +---------------------------------------------------+--------------+--------+------------+------------+ diff --git a/doc/unsorted/bcfg2.conf-options.txt b/doc/unsorted/bcfg2.conf-options.txt deleted file mode 100644 index 57e26cbd2..000000000 --- a/doc/unsorted/bcfg2.conf-options.txt +++ /dev/null @@ -1,19 +0,0 @@ -.. -*- 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/unsorted/dynamic_groups.txt b/doc/unsorted/dynamic_groups.txt deleted file mode 100644 index 11535dc8b..000000000 --- a/doc/unsorted/dynamic_groups.txt +++ /dev/null @@ -1,27 +0,0 @@ -.. -*- mode: rst -*- - -.. _unsorted-dynamic_groups: - -============== -Dynamic Groups -============== - -Bcfg2 supports the use of dynamic groups. These groups are not included -in a client's profile group, but instead are derived from the results -of probes executed on the client. These dynamic groups need not already -exist in ``Metadata/groups.xml``. If a dynamic group is defined in -``Metadata/groups.xml``, clients that include this group will also get -all included groups and bundles. - -Setting up dynamic groups -========================= - -In order to define a dynamic group, setup a probe that outputs the text -based on system properties:: - - group:groupname - -This output is processed by the Bcfg2 server, and results in dynamic -group membership in groupname for the client. See the :ref:`Probes -<server-plugins-probes-index>` page for a more thorough description -of probes. diff --git a/doc/unsorted/emacs_snippet.txt b/doc/unsorted/emacs_snippet.txt index b9f7fd25b..4eefb4583 100644 --- a/doc/unsorted/emacs_snippet.txt +++ b/doc/unsorted/emacs_snippet.txt @@ -31,7 +31,7 @@ More snippets are under development. ("<Group" "<Group name='${1:groupname}> $0 </Group>" nil) - ("<Config" "<ConfigFile name='${1:filename}'/> + ("<Path" "<Path name='${1:filename}'/> $0" nil) ("<Service" "<Service name='${1:svcname}'/> $0" nil) diff --git a/doc/unsorted/howtos.txt b/doc/unsorted/howtos.txt index 0c5b482d9..81b38e54d 100644 --- a/doc/unsorted/howtos.txt +++ b/doc/unsorted/howtos.txt @@ -12,7 +12,7 @@ Here are several howtos that describe different aspects of Bcfg2 deployment * AnnotatedExamples - a description of basic Bcfg2 specification operations * BuildingDebianPackages - How to build debian packages * :ref:`appendix-guides-gentoo` - Issues specific to running Bcfg2 on Gentoo -* :ref:`server-plugins-probes-index` - How to use Probes to gather information from a client machine. +* :ref:`server-plugins-probes` - How to use Probes to gather information from a client machine. * :ref:`client-tools-actions` - How to use Actions -* :ref:`unsorted-dynamic_groups` - Using dynamic groups +* :ref:`server-plugins-probes-dynamic-groups` - Using dynamic groups * :ref:`client-modes-paranoid` - How to run an update in paranoid mode diff --git a/doc/unsorted/vim_snippet.txt b/doc/unsorted/vim_snippet.txt index e4fda7eca..4598b5c1d 100644 --- a/doc/unsorted/vim_snippet.txt +++ b/doc/unsorted/vim_snippet.txt @@ -30,9 +30,9 @@ that allow quick composition of bundles and base files. <Group name='${1:groupname}'> ${2} </Group> - # ConfigFile - snippet <Config - <ConfigFile name='${1:filename}'/> + # Path + snippet <Path + <Path name='${1:filename}'/> # Service snippet <Service <Service name='${1:svcname}'/> diff --git a/doc/unsorted/writing_specification.txt b/doc/unsorted/writing_specification.txt index e7763cee1..f9dd30a14 100644 --- a/doc/unsorted/writing_specification.txt +++ b/doc/unsorted/writing_specification.txt @@ -132,15 +132,7 @@ The following is an annotated copy of a bundle: .. code-block:: xml <Bundle> - <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'/> - <Path name='/etc/ssh/ssh_host_rsa_key.pub'/> - <Path name='/etc/ssh/ssh_host_key'/> - <Path name='/etc/ssh/ssh_host_key.pub'/> - <Path name='/etc/ssh/sshd_config'/> - <Path name='/etc/ssh/ssh_config'/> - <Path name='/etc/ssh/ssh_known_hosts'/> + <Path glob='/etc/ssh/*'/> <Group name='rpm'> <Package name='openssh'/> <Package name='openssh-askpass'/> @@ -171,23 +163,7 @@ can be used in bundles) +----------------+-------------------------------+ | Group | Entry | +================+===============================+ -| all | /etc/ssh/ssh_host_dsa_key | -+----------------+-------------------------------+ -| all | /etc/ssh/ssh_host_rsa_key | -+----------------+-------------------------------+ -| all | /etc/ssh/ssh_host_dsa_key.pub | -+----------------+-------------------------------+ -| all | /etc/ssh/ssh_host_rsa_key.pub | -+----------------+-------------------------------+ -| all | /etc/ssh/ssh_host_key | -+----------------+-------------------------------+ -| all | /etc/ssh/ssh_host_key.pub | -+----------------+-------------------------------+ -| all | /etc/ssh/sshd_config | -+----------------+-------------------------------+ -| all | /etc/ssh/ssh_config | -+----------------+-------------------------------+ -| all | /etc/ssh/ssh_known_hosts | +| all | /etc/ssh/* | +----------------+-------------------------------+ | rpm | Package openssh | +----------------+-------------------------------+ |