summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/_templates/indexsidebar.html11
-rw-r--r--doc/appendix/configuration/mrepo.txt26
-rw-r--r--doc/appendix/contributors.txt8
-rw-r--r--doc/appendix/guides/centos.txt114
-rw-r--r--doc/appendix/guides/gentoo.txt73
-rw-r--r--doc/appendix/guides/using-bcfg2-with-centos.txt8
-rw-r--r--doc/conf.py8
-rw-r--r--doc/development/index.txt1
-rw-r--r--doc/development/plugins.txt4
-rw-r--r--doc/development/setup.txt7
-rw-r--r--doc/development/unit-testing.txt25
-rw-r--r--doc/getting_started/index.txt2
-rw-r--r--doc/installation/distributions.txt19
-rw-r--r--doc/server/admin/bundle.txt10
-rw-r--r--doc/server/plugins/connectors/templatehelper.txt74
-rw-r--r--doc/server/plugins/generators/packages.txt83
-rw-r--r--doc/server/plugins/probes/group.txt2
-rw-r--r--doc/server/plugins/probes/index.txt2
18 files changed, 301 insertions, 176 deletions
diff --git a/doc/_templates/indexsidebar.html b/doc/_templates/indexsidebar.html
new file mode 100644
index 000000000..39916315d
--- /dev/null
+++ b/doc/_templates/indexsidebar.html
@@ -0,0 +1,11 @@
+<!-- FIXME: Add download page with pdf/html/txt archives of these documents
+ <h3>Download</h3>
+ <p><a href="{{ pathto('download') }}">Download these documents</a></p>
+-->
+
+ <h3>Docs for other versions</h3>
+ <ul>
+ <li><a href="http://docs.bcfg2.org/1.1/">Bcfg2 1.1 (stable)</a></li>
+ <li><a href="http://docs.bcfg2.org/1.2/">Bcfg2 1.2 (stable)</a></li>
+ <li><a href="http://docs.bcfg2.org/dev/">Bcfg2 development documentation</a></li>
+ </ul>
diff --git a/doc/appendix/configuration/mrepo.txt b/doc/appendix/configuration/mrepo.txt
index 309cd6779..c1bdb3fed 100644
--- a/doc/appendix/configuration/mrepo.txt
+++ b/doc/appendix/configuration/mrepo.txt
@@ -7,7 +7,7 @@
mrepo
=====
-This section describes how to setup an `mrepo`_ mirror.
+.. This section describes how to setup an `mrepo`_ mirror.
`mrepo`_ builds a local APT/Yum RPM repository from local ISO files,
downloaded updates, and extra packages from 3rd party repositories. It
@@ -68,3 +68,27 @@ Update the repositories
::
mrepo -ug
+
+Example sources.xml file
+------------------------
+
+.. code-block:: xml
+
+ <Sources>
+ <!-- CentOS (5.4) sources -->
+ <YUMSource>
+ <Group>centos-5.4</Group>
+ <RawURL>http://mrepo/centos5-x86_64/RPMS.os</RawURL>
+ <Arch>x86_64</Arch>
+ </YUMSource>
+ <YUMSource>
+ <Group>centos-5.4</Group>
+ <RawURL>http://mrepo/centos5-x86_64/RPMS.updates</RawURL>
+ <Arch>x86_64</Arch>
+ </YUMSource>
+ <YUMSource>
+ <Group>centos-5.4</Group>
+ <RawURL>http://mrepo/centos5-x86_64/RPMS.extras</RawURL>
+ <Arch>x86_64</Arch>
+ </YUMSource>
+ </Sources>
diff --git a/doc/appendix/contributors.txt b/doc/appendix/contributors.txt
index ebc49d364..1afc62706 100644
--- a/doc/appendix/contributors.txt
+++ b/doc/appendix/contributors.txt
@@ -11,7 +11,7 @@ Contributors
..
This is list is no longer in chronological order like the
- AUTHORS file because it's easier to maintain (for me).
+ AUTHORS file because it's easier to maintain.
Automatically sorted.
In alphabetical order of the given name:
@@ -22,6 +22,8 @@ In alphabetical order of the given name:
which was used in the Bcfg2 client.
- Chris Vuletich <vuletich@mcs.anl.gov> wrote some SSL code and the
verification debugging code.
+- Chris St. Pierre <stpierreca@ornl.gov> (re)wrote bcfg2-lint and has
+ made other miscellaneous contributions.
- Cory Lueninghoener <cory@mcs.anl.gov> wrote the showentries function
in ``bcfg2-info``.
- Daniel Clark <dclark@pobox.com> created encap packages for bcfg2 and
@@ -31,7 +33,7 @@ In alphabetical order of the given name:
- David Strauss worked on CentOS, RHEL, Yum, and Bazaar VCS support.
- Ed Smith <esmith4@inf.ed.ac.uk> has done substantial hardening of the
Bcfg client and server and implemented a common logging infrastructure.
-- Fabian Affolter <fabian@bernewireless.net> made some patches, added
+- Fabian Affolter <mail@fabian-affolter.ch> made some patches, added
some new features and plugins, and restructured the manual for Bcfg2.
- Jack Neely <jjneely@ncsu.edu> worked on YUMng.
- James Yang <jjyang@mcs.anl.gov> worked on ``bcfg2-admin`` and
@@ -45,7 +47,7 @@ In alphabetical order of the given name:
- Ken Raffenetti <raffenet@mcs.anl.gov> and Rick Bradshaw have written the
Hostbase plugin.
- Michael Jinks <mjinks@uchicago.edu> wrote the Gentoo tool drivers.
-- Narayan Desai <desai@mcs.anl.gov> has written most of bcfg2, including all
+- Narayan Desai <desai@mcs.anl.gov> has written most of Bcfg2, including all
parts not explicitly mentioned in this file.
- Patrick Ruckstuhl fixed bugs in the templating.
- Pedro Flores made the Reporting system design help.
diff --git a/doc/appendix/guides/centos.txt b/doc/appendix/guides/centos.txt
index 2bb3edc2b..50334ccbc 100644
--- a/doc/appendix/guides/centos.txt
+++ b/doc/appendix/guides/centos.txt
@@ -17,7 +17,7 @@ Install Bcfg2
The fastest way to get Bcfg2 onto your system is to use Yum or
your preferred package management tool. We'll be using the ones
that are distributed through EPEL_, but depending on your aversion
-to risk you could download an RPM from other places as well. See
+to risk you could download an RPM from other places as well. See
:ref:`getting_started-using_bcfg2-with-centos` for information about
building Bcfg2 from source and making your own packages.
@@ -102,20 +102,20 @@ Run bcfg2 to be sure you are able to communicate with the server::
Excluding Packages in global exclude list
Finished
Loaded tool drivers:
- Action Chkconfig POSIX YUMng
+ Action Chkconfig POSIX YUMng
Phase: initial
- Correct entries: 0
- Incorrect entries: 0
- Total managed entries: 0
- Unmanaged entries: 208
+ Correct entries: 0
+ Incorrect entries: 0
+ Total managed entries: 0
+ Unmanaged entries: 208
Phase: final
- Correct entries: 0
- Incorrect entries: 0
- Total managed entries: 0
- Unmanaged entries: 208
+ Correct entries: 0
+ Incorrect entries: 0
+ Total managed entries: 0
+ Unmanaged entries: 208
No ca is specified. Cannot authenticate the server with SSL.
@@ -147,20 +147,20 @@ Now if you run the client, no more warning::
Excluding Packages in global exclude list
Finished
Loaded tool drivers:
- Action Chkconfig POSIX YUMng
+ Action Chkconfig POSIX YUMng
Phase: initial
- Correct entries: 0
- Incorrect entries: 0
- Total managed entries: 0
- Unmanaged entries: 208
+ Correct entries: 0
+ Incorrect entries: 0
+ Total managed entries: 0
+ Unmanaged entries: 208
Phase: final
- Correct entries: 0
- Incorrect entries: 0
- Total managed entries: 0
- Unmanaged entries: 208
+ Correct entries: 0
+ Incorrect entries: 0
+ Total managed entries: 0
+ Unmanaged entries: 208
Bring your first machine under Bcfg2 control
============================================
@@ -173,7 +173,7 @@ Setup the :ref:`server-plugins-generators-packages` plugin
----------------------------------------------------------
First, replace **Pkgmgr** with **Packages** in the plugins
-line of ``bcfg2.conf``. Then create Packages layout (as per
+line of ``bcfg2.conf``. Then create Packages layout (as per
:ref:`packages-exampleusage`) in ``/var/lib/bcfg2``
.. note:: I am using the RawURL syntax here since we are using `mrepo`_
@@ -291,30 +291,30 @@ Now if we run the client, we can see what this has done for us.::
Excluding Packages in global exclude list
Finished
Loaded tool drivers:
- Action Chkconfig POSIX YUMng
+ Action Chkconfig POSIX YUMng
Package pam failed verification.
Phase: initial
- Correct entries: 94
- Incorrect entries: 1
- Total managed entries: 95
- Unmanaged entries: 113
+ Correct entries: 94
+ Incorrect entries: 1
+ Total managed entries: 95
+ Unmanaged entries: 113
In dryrun mode: suppressing entry installation for:
Package:pam
Phase: final
- Correct entries: 94
- Incorrect entries: 1
+ Correct entries: 94
+ Incorrect entries: 1
Package:pam
- Total managed entries: 95
- Unmanaged entries: 113
+ Total managed entries: 95
+ Unmanaged entries: 113
Interesting, our **pam** package failed verification. What does this
mean? Let's have a look::
[root@centos ~]# rpm --verify pam
- ....L... c /etc/pam.d/system-auth
+ ....L... c /etc/pam.d/system-auth
Sigh, it looks like the default RPM install for pam fails to verify
using its own verification process (trust me, it's not the only one). At
@@ -336,23 +336,23 @@ entries?::
Excluding Packages in global exclude list
Finished
Loaded tool drivers:
- Action Chkconfig POSIX YUMng
+ Action Chkconfig POSIX YUMng
Extra Package openssh-clients 4.3p2-36.el5_4.4.x86_64.
Extra Package libuser 0.54.7-2.1el5_4.1.x86_64.
...
Phase: initial
- Correct entries: 95
- Incorrect entries: 0
- Total managed entries: 95
- Unmanaged entries: 113
+ Correct entries: 95
+ Incorrect entries: 0
+ Total managed entries: 95
+ Unmanaged entries: 113
Phase: final
- Correct entries: 95
- Incorrect entries: 0
- Total managed entries: 95
- Unmanaged entries: 113
+ Correct entries: 95
+ Incorrect entries: 0
+ Total managed entries: 95
+ Unmanaged entries: 113
Package:at
Package:avahi
Package:avahi-compat-libdns_sd
@@ -394,22 +394,22 @@ package::
Excluding Packages in global exclude list
Finished
Loaded tool drivers:
- Action Chkconfig POSIX YUMng
+ Action Chkconfig POSIX YUMng
Extra Package gpg-pubkey e8562897-459f07a4.None.
Extra Package gpg-pubkey 217521f6-45e8a532.None.
Phase: initial
- Correct entries: 187
- Incorrect entries: 0
- Total managed entries: 187
- Unmanaged entries: 16
+ Correct entries: 187
+ Incorrect entries: 0
+ Total managed entries: 187
+ Unmanaged entries: 16
Phase: final
- Correct entries: 187
- Incorrect entries: 0
- Total managed entries: 187
- Unmanaged entries: 16
+ Correct entries: 187
+ Incorrect entries: 0
+ Total managed entries: 187
+ Unmanaged entries: 16
Package:gpg-pubkey
Service:atd
Service:avahi-daemon
@@ -562,20 +562,20 @@ Now we run the client and see there are no more unmanaged entries!::
Excluding Packages in global exclude list
Finished
Loaded tool drivers:
- Action Chkconfig POSIX YUMng
+ Action Chkconfig POSIX YUMng
Phase: initial
- Correct entries: 205
- Incorrect entries: 0
- Total managed entries: 205
- Unmanaged entries: 0
+ Correct entries: 205
+ Incorrect entries: 0
+ Total managed entries: 205
+ Unmanaged entries: 0
Phase: final
- Correct entries: 205
- Incorrect entries: 0
- Total managed entries: 205
- Unmanaged entries: 0
+ Correct entries: 205
+ Incorrect entries: 0
+ Total managed entries: 205
+ Unmanaged entries: 0
.. warning::
diff --git a/doc/appendix/guides/gentoo.txt b/doc/appendix/guides/gentoo.txt
index d635e310b..da4acef19 100644
--- a/doc/appendix/guides/gentoo.txt
+++ b/doc/appendix/guides/gentoo.txt
@@ -16,28 +16,38 @@ let the list know if you find errors or omissions.
Installing Bcfg2
================
-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.
+Early in July 2008, Bcfg2 was added to the Gentoo portage tree.
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-libs/libgamin[python]``
* ``dev-python/lxml``
Clients will need at least:
* ``app-portage/gentoolkit``
+Portage installs from source
+============================
+
+.. versionadded:: 1.3.0
+
+By default the client will run with the ``--gitbinpkgonly`` option. If
+you want your client to install packages from source (rather than
+having a binary build host as seen below), you can set the following in
+``/etc/bcfg2.conf``.::
+
+ [Portage]
+ binpkgonly = false
+
Package Repository
==================
+.. note: This is only necessary for using binary packages.
+
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 :envvar:`PORTAGE_BINHOST` environment variable.
@@ -109,60 +119,17 @@ Configuring Client Machines
Set up ``/etc/bcfg2.conf`` the way you would for any other Bcfg2 client.
In ``make.conf``, set *PORTAGE_BINHOST* to point to the URI of
-your package repository. You may want to create versions of
+your package repository. You may want to create versions of
``make.conf`` for each package repository you maintain, with
appropriate *PORTAGE_BINHOST* URI's in each, and associated with
that package archive's group under ``Cfg`` -- for example, we have
-``Cfg/etc/make.conf/make.conf.G99_gentoo-200701-vmware``. If a client
+``Cfg/etc/make.conf/make.conf.G99_gentoo-200701-vmware``. If a client
host switches groups, and the new group needs a different set of packages,
everything should just fall into place.
Pitfalls
========
-Package Verification Issues
----------------------------
-
-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
-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
-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,
-leading to noise like this::
-
- # equery check openssh
- [ Checking net-misc/openssh-4.5_p1 ]
- !!! /etc/ssh/sshd_config has incorrect md5sum
- !!! /usr/bin/slogin does not point to ssh
- !!! /usr/share/man/man1/slogin.1.gz does not point to ssh.1.gz
- !!! /etc/ssh/ssh_config has incorrect md5sum
- * 62 out of 66 files good
-
-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
-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.
-
-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
-series of ``Rules`` definitions according to what the package database
-thinks it should find, and/or stage copies of affected files under
-``Cfg``, and associate those rules and files with the affected package in
-a bundle? Annoying but possibly necessary if you want your stats file
-to look good.
-
/boot
-----
diff --git a/doc/appendix/guides/using-bcfg2-with-centos.txt b/doc/appendix/guides/using-bcfg2-with-centos.txt
index cd00e5e79..6a48fc5da 100644
--- a/doc/appendix/guides/using-bcfg2-with-centos.txt
+++ b/doc/appendix/guides/using-bcfg2-with-centos.txt
@@ -23,11 +23,13 @@ While you can go about building all these things from source, this
how to will try and meet the dependencies using packages from EPEL_
or RPMforge_. The *el5* package should be compatible with CentOS 5.x.
-EPEL_::
+EPEL_ for 5.x ::
+ [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-3.noarch.rpm
+EPEL_ for 6.x ::
+ [root@centos ~]# rpm -Uvh http://download.fedoraproject.org/pub/epel/6/i386/epel-release-6-5.noarch.rpm
-RPMforge_::
+RPMforge_ for 5.x ::
[root@centos ~]# rpm -Uvh http://dag.wieers.com/rpm/packages/rpmforge-release/rpmforge-release-0.3.6-1.el5.rf.x86_64.rpm
diff --git a/doc/conf.py b/doc/conf.py
index 38160715d..5903b009a 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -104,7 +104,9 @@ html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
-#html_theme_options = {}
+html_theme_options = {
+ "collapsiblesidebar": "true"
+}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
@@ -139,7 +141,9 @@ html_last_updated_fmt = '%b %d, %Y'
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+html_sidebars = {
+ 'index': 'indexsidebar.html'
+}
# Additional templates that should be rendered to pages, maps page names to
# template names.
diff --git a/doc/development/index.txt b/doc/development/index.txt
index 352000dc8..2a54bfad8 100644
--- a/doc/development/index.txt
+++ b/doc/development/index.txt
@@ -39,3 +39,4 @@ git access. Mail the :ref:`help-mailinglist` for details.
testing
documentation
docstyleguide
+ unit-testing
diff --git a/doc/development/plugins.txt b/doc/development/plugins.txt
index 15b512365..b2b70f553 100644
--- a/doc/development/plugins.txt
+++ b/doc/development/plugins.txt
@@ -164,7 +164,6 @@ Example Connector
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):
@@ -195,13 +194,10 @@ do so. We will call our new plugin `MyMetadata`.
.. 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):
diff --git a/doc/development/setup.txt b/doc/development/setup.txt
index e9fc6e1e5..b04bce3fe 100644
--- a/doc/development/setup.txt
+++ b/doc/development/setup.txt
@@ -12,13 +12,8 @@ Checking Out a Copy of the Code
git clone git://git.mcs.anl.gov/bcfg2.git
-* Create link to :file:`src/lib`::
-
- cd bcfg2
- ln -s src/lib Bcfg2
-
* Add :file:`bcfg2/src/sbin` to your :envvar:`PATH` environment variable
-* Add :file:`bcfg2` to your :envvar:`PYTHONPATH` environment variable
+* Add :file:`bcfg2/src/lib` to your :envvar:`PYTHONPATH` environment variable
Using a Virtual Environment for Development
diff --git a/doc/development/unit-testing.txt b/doc/development/unit-testing.txt
new file mode 100644
index 000000000..30217dcc5
--- /dev/null
+++ b/doc/development/unit-testing.txt
@@ -0,0 +1,25 @@
+.. -*- mode: rst -*-
+
+.. _development-unit-testing:
+
+==================
+Bcfg2 unit testing
+==================
+
+.. _Python Mock Module: http://python-mock.sourceforge.net/
+.. _Python Nose: http://readthedocs.org/docs/nose/en/latest/
+
+You will first need to install the `Python Mock Module`_ and `Python
+Nose`_ modules. You can then run the existing tests with the
+following.::
+
+ cd testsuite
+ nosetests
+
+You should see output something like the following::
+
+ ..................................................
+ ----------------------------------------------------------------------
+ Ran 50 tests in 0.121s
+
+ OK
diff --git a/doc/getting_started/index.txt b/doc/getting_started/index.txt
index e7075c33f..034584014 100644
--- a/doc/getting_started/index.txt
+++ b/doc/getting_started/index.txt
@@ -236,7 +236,7 @@ Next Steps
Several other utilities can help from this point on:
:ref:`bcfg2-info <server-bcfg2-info>` is a utility that
-instantiates a copy of the bcfg2 server core (minus the networking code)
+instantiates a copy of the Bcfg2 server core (minus the networking code)
for examination. From this, you can directly query:
* Client Metadata
diff --git a/doc/installation/distributions.txt b/doc/installation/distributions.txt
index 383943e9f..3dcfd7721 100644
--- a/doc/installation/distributions.txt
+++ b/doc/installation/distributions.txt
@@ -10,6 +10,17 @@ 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.
+Alpine Linux
+============
+
+Packages for `Alpine Linux`_ are available in the `testing`_ repository.
+Just use `apk` to perform the installation ::
+
+ apk add bcfg2 bcfg2-server -U -X http://dl-3.alpinelinux.org/alpine/edge/testing/ --allow-untrusted
+
+.. _Alpine Linux: http://www.alpinelinux.org/
+.. _testing: http://git.alpinelinux.org/cgit/aports/tree/testing/bcfg2
+
ArchLinux
=========
@@ -101,13 +112,15 @@ 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
+[#f1]_. The *el5* and the *el6* package should be compatible
with `CentOS`_ 5.x/6.x and `Scientific Linux`_.
-EPEL_::
-
+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 ::
+ [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::
[root@centos ~]# yum install bcfg2-server bcfg2
diff --git a/doc/server/admin/bundle.txt b/doc/server/admin/bundle.txt
index 101666bb9..e9cb79781 100644
--- a/doc/server/admin/bundle.txt
+++ b/doc/server/admin/bundle.txt
@@ -8,13 +8,17 @@ bundle
For a list of all available xml bundles use ``list-xml``. ``list-genshi``
will list all available genshi bundles.::
- # bcfg2-admin bundle list-xml
- # bcfg2-admin bundle list-genshi
+.. code-block:: sh
+
+ # bcfg2-admin bundles list-xml
+ # bcfg2-admin bundles list-genshi
``show`` provides an interactive dialog to get details about the available
bundles.::
- # bcfg2-admin bundle show
+.. code-block:: sh
+
+ # bcfg2-admin bundles show
Available bundles (Number of bundles: 4)
----------------------------------------
[0] motd.xml
diff --git a/doc/server/plugins/connectors/templatehelper.txt b/doc/server/plugins/connectors/templatehelper.txt
new file mode 100644
index 000000000..24d7f18b5
--- /dev/null
+++ b/doc/server/plugins/connectors/templatehelper.txt
@@ -0,0 +1,74 @@
+.. -*- mode: rst -*-
+
+.. _server-plugins-connectors-templatehelper:
+
+==============
+TemplateHelper
+==============
+
+The TemplateHelper plugin is a connector plugin that adds Python
+classes and methods to client metadata instances for use in
+templates. This allows you to easily reuse code that is common
+amongst multiple templates and add convenience methods.
+
+Using TemplateHelper
+====================
+
+First, ``mkdir /var/lib/bcfg2/TemplateHelper`` and add
+**TemplateHelper** to your ``plugins`` line in ``/etc/bcfg2.conf``.
+Restart ``bcfg2-server``.
+
+Now, any ``.py`` file placed in ``/var/lib/bcfg2/TemplateHelper/``
+will be read and added to matching client metadata objects. See
+:ref:`writing-templatehelpers` below for more information on how to
+write TemplateHelper scripts.
+
+TemplateHelper supports group- and host-specific helpers, so you could
+create, e.g., ``foo.py.G80_test`` to create a helper that only applied
+to machines in the group ``test``.
+
+.. _writing-templatehelpers:
+
+Writing Helpers
+===============
+
+A helper module is just a Python module with three special conditions:
+
+* The filename must end with ``.py`` (before any specificity
+ strings, e.g., ``.G80_foo`` or ``.H_blah.example.com``
+* The module must have an attribute, ``__export__``, that lists all of
+ the classes, functions, variables, or other symbols you wish to
+ export from the module.
+* ``data``, ``handle_event``, ``name``, and ``specific`` are reserved
+ names. You should not include symbols with a reserved name in
+ ``__export__``. Additionally, including symbols that start with an
+ underscore or double underscore is bad form, and may also produce
+ errors.
+
+See ``examples/TemplateHelper`` for examples of helper modules.
+
+Usage
+=====
+
+Specific helpers can be referred to in
+templates as ``metadata.TemplateHelper[<modulename>]``. That accesses
+a HelperModule object will has, as attributes, all symbols listed in
+``__export__``. For example, consider this helper module::
+
+ __export__ = ["hello"]
+
+ def hello(metadata):
+ return "Hello, %s!" % metadata.hostname
+
+To use this in a TGenshi template, we could do::
+
+ ${metadata.TemplateHelper['hello'].hello(metadata)}
+
+The template would produce::
+
+ Hello, foo.example.com!
+
+Note that the client metadata object is not passed to a helper module
+in any magical way; if you want to access the client metadata object
+in a helper function or class, you must pass the object to the
+function manually.
diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt
index 900162aaa..62574be76 100644
--- a/doc/server/plugins/generators/packages.txt
+++ b/doc/server/plugins/generators/packages.txt
@@ -56,19 +56,19 @@ member clients.
.. versionadded:: 1.2.0
Magic OS groups can be disabled in Bcfg2 1.2 and greater by setting
- ``magic_groups`` to ``0`` in ``Packages/packages.conf``. This may
+ ``magic_groups`` to ``0`` in ``Packages/packages.conf``. This may
give you greater flexibility in determining which source types to
- use for which OSes. Magic architecture groups cannot be disabled.
+ use for which OSes. Magic architecture groups cannot be disabled.
Limiting sources to groups
==========================
``Packages/sources.xml`` processes ``<Group>`` and ``<Client>`` tags
-just like Bundles. In addition to any groups or clients specified
+just like Bundles. In addition to any groups or clients specified
that way, clients must
be a member of the appropriate architecture group as specified in a
-Source stanza. In total, in order for a source to be associated with
+Source stanza. In total, in order for a source to be associated with
a client, the client must be in one of the magic groups (debian,
ubuntu, or nexenta), any explicit groups or clients specified in
``sources.xml``, and any specified architecture groups.
@@ -161,7 +161,7 @@ Handling GPG Keys
If you have yum libraries installed, Packages can automatically handle
GPG signing keys for Yum and Pulp repositories. (You do not need to
use the native yum resolver; if yum libraries are available, GPG
-signing keys can be handled automatically.) Simply specify the URL to
+signing keys can be handled automatically.) Simply specify the URL to
the GPG key(s) for a repository in ``sources.xml``::
<Source type="yum"
@@ -205,14 +205,13 @@ something like this::
.. versionadded:: 1.1.0
- The default behavior of the Packages plugin is to not make
- any assumptions about which packages you want to have added
- automatically. For that reason, neither **Recommended** nor
- **Suggested** packages are added as dependencies by default. You
- will notice that the default behavior for apt is to add Recommended
- packages as dependencies. You can configure the Packages plugin to
- add recommended packages by adding the ``recommended`` attribute,
- e.g.:
+ The default behavior of the Packages plugin is to not make any
+ assumptions about which packages you want to have added automatically
+ [#f1]_. For that reason, neither **Recommended** nor **Suggested**
+ packages are added as dependencies by default. You will notice
+ that the default behavior for apt is to add Recommended packages as
+ dependencies. You can configure the Packages plugin to add recommended
+ packages by adding the ``recommended`` attribute, e.g.:
.. code-block:: xml
@@ -221,6 +220,14 @@ something like this::
.. warning:: You must regenerate the Packages cache when adding or
removing the recommended attribute.
+ .. [#f1] Bcfg2 will by default add **Essential** packages to the
+ client specification. You can disable this behavior by
+ setting the ``essential`` attribute to *false*:
+
+ .. code-block:: xml
+
+ <Source type="apt" essential="false" ...>
+
Yum sources can be similarly specified::
<Sources>
@@ -335,7 +342,7 @@ updated.
Availability
============
-Support for clients using yum and apt is currently available. Support for
+Support for clients using yum and apt is currently available. Support for
other package managers (Portage, Zypper, IPS, etc) remain to be added.
Validation
@@ -351,7 +358,7 @@ Limitations
Packages does not do traditional caching as other plugins
do. Modifying sources in the Packages ``sources.xml`` file requires a
-server restart for the time being. You do not have to restart the
+server restart for the time being. You do not have to restart the
server after changing ``packages.conf`` or after adding new sources to
``sources.xml``.
@@ -384,9 +391,9 @@ Then add the corresponding Path entry to your Yum bundle.
.. versionadded:: 1.1.0
APT repository information can be generated automatically from
-software sources using :doc:`./tgenshi/index` or :doc:`./tcheetah`. A
+software sources using :doc:`./tgenshi/index` or :doc:`./tcheetah`. A
list of source urls are exposed in the client's metadata as
-``metadata.Packages.sources``. E.g.::
+``metadata.Packages.sources``. E.g.::
# bcfg2 maintained apt
@@ -404,7 +411,7 @@ Using Native Yum Libraries
By default, Bcfg2 uses an internal implementation of Yum's dependency
resolution and other routines so that the Bcfg2 server can be run on a
-host that does not support Yum itself. If you run the Bcfg2 server on
+host that does not support Yum itself. If you run the Bcfg2 server on
a machine that does have Yum libraries, however, you can enable use of
those native libraries in Bcfg2 by setting ``use_yum_libraries`` to
``1`` in the ``[yum]`` section of ``Packages/packages.conf``.
@@ -418,7 +425,7 @@ Benefits to this include:
Drawbacks include:
-* More disk I/O. In some cases, you may have to raise the open file
+* More disk I/O. In some cases, you may have to raise the open file
limit for the user who runs your Bcfg2 server process, particularly
if you have a lot of repositories.
* Resolution of package dependencies is slower in some cases,
@@ -433,8 +440,8 @@ Configuring the Yum Helper
Due to poor memory management by the Yum API, the long-lived
bcfg2-server process uses an external short-lived helper,
``bcfg2-yum-helper``, to do the actual Yum API calls for native yum
-library support. By default, Bcfg2 looks for this helper at
-``/usr/sbin/bcfg2-yum-helper``. If you have installed the helper
+library support. By default, Bcfg2 looks for this helper at
+``/usr/sbin/bcfg2-yum-helper``. If you have installed the helper
elsewhere, you will need to configure that location with the
``helper`` option in the ``[yum]`` section, e.g.::
@@ -448,11 +455,11 @@ Setting Yum Options
In ``Packages/packages.conf``, any options you set in the ``[yum]``
section other than ``use_yum_libraries`` and ``helper`` will be passed
along verbatim to the configuration of the Yum objects used in the
-Bcfg2 server. The following options are set by default, and should
+Bcfg2 server. The following options are set by default, and should
not generally be overridden:
* ``cachedir`` is set to a hashed value unique to each distinct Yum
- configuration. Don't set this unless you know what you're doing.
+ configuration. Don't set this unless you know what you're doing.
* ``keepcache`` is set to ``0``; there is no benefit to changing this.
* ``sslverify`` is set to ``0``; change this if you know what you're
doing.
@@ -462,16 +469,16 @@ not generally be overridden:
Package Groups
--------------
-Yum package groups are supported by the native Yum libraries. To
+Yum package groups are supported by the native Yum libraries. To
include a package group, use the ``group`` attribute of the
-``Package`` tag. You can use either the short group ID or the long
+``Package`` tag. You can use either the short group ID or the long
group name::
<Package group="SNMP Support"/>
<Package group="system-management-snmp"/>
By default, only those packages considered the "default" packages in a
-group will be installed. You can change this behavior using the
+group will be installed. You can change this behavior using the
"type" attribute::
<Package group="development" type="optional"/>
@@ -485,7 +492,7 @@ Valid values of "type" are:
including mandatory, default, and optional packages.
You can view the packages in a group by category with the ``yum
-groupinfo`` command. More information about the different levels can
+groupinfo`` command. More information about the different levels can
be found at
http://fedoraproject.org/wiki/How_to_use_and_edit_comps.xml_for_package_groups#Installation
@@ -497,7 +504,7 @@ Pulp Support
.. versionadded:: 1.2.0
Bcfg2 contains explicit support for repositories managed by Pulp
-(http://pulpproject.org/). Due to the amount of data about a
+(http://pulpproject.org/). Due to the amount of data about a
repository that can be retrieved directly from Pulp, the only thing
necessary to configure a Pulp repo is the repo ID::
@@ -509,7 +516,7 @@ necessary to configure a Pulp repo is the repo ID::
</Group>
</Sources>
-Pulp sources require some additional configuration. First, the Bcfg2
+Pulp sources require some additional configuration. First, the Bcfg2
server must have a valid ``/etc/pulp/consumer/consumer.conf`` that is
readable by the user your Bcfg2 server runs as; the Pulp server,
URLs, and so on, are determined from this.
@@ -519,7 +526,7 @@ options in the ``[pulp]`` section:
* ``username`` and ``password``: The username and password of a Pulp
user that will be used to register new clients and bind them to
- repositories. Membership in the default ``consumer-users`` role is
+ repositories. Membership in the default ``consumer-users`` role is
sufficient.
Bcfg2 clients using Pulp sources will be registered to the Pulp server
@@ -640,7 +647,7 @@ packages.conf
=============
``packages.conf`` contains miscellaneous configuration options for the
-Packages plugin. Any booleans in the config file accept the values
+Packages plugin. Any booleans in the config file accept the values
"1", "yes", "true", and "on" for True, and "0", "no", "false", and
"off" for False
@@ -649,18 +656,18 @@ It understands the following directives:
[global] section
----------------
-* ``resolver``: Enable dependency resolution. Default is ``1``
+* ``resolver``: Enable dependency resolution. Default is ``1``
(true). For historical reasons, this also accepts "enabled" and
"disabled".
-* ``metadata``: Enable metadata processing. Default is ``1``
+* ``metadata``: Enable metadata processing. Default is ``1``
(true). For historical reasons, this also accepts "enabled" and
"disabled".
-* ``yum_config``: The path at which to generate Yum configs. No
+* ``yum_config``: The path at which to generate Yum configs. No
default.
-* ``apt_config``: The path at which to generate APT configs. No
+* ``apt_config``: The path at which to generate APT configs. No
default.
* ``gpg_keypath``: The path on the client RPM GPG keys will be copied
- to before they are imported on the client. Default is
+ to before they are imported on the client. Default is
"/etc/pki/rpm-gpg".
* ``version``: Set the version attribute used when binding
Packages. Default is ``auto``.
@@ -669,7 +676,7 @@ It understands the following directives:
-------------
* ``use_yum_libraries``: Whether or not to use the :ref:`native yum
- library support <native-yum-libraries>`. Default is ``0`` (false).
+ library support <native-yum-libraries>`. Default is ``0`` (false).
All other options in the ``[yum]`` section will be passed along
verbatim to the Yum configuration if you are using the native Yum
@@ -680,5 +687,5 @@ library support.
* ``username`` and ``password``: The username and password of a Pulp
user that will be used to register new clients and bind them to
- repositories. Membership in the default ``consumer-users`` role is
+ repositories. Membership in the default ``consumer-users`` role is
sufficient.
diff --git a/doc/server/plugins/probes/group.txt b/doc/server/plugins/probes/group.txt
index 5c4d6ecb1..03c13db42 100644
--- a/doc/server/plugins/probes/group.txt
+++ b/doc/server/plugins/probes/group.txt
@@ -52,7 +52,7 @@ Probe used to dynamically set client groups based on OS/distro.
# redhat based
if [ -x /bin/rpm ]; then
OUTPUT="${OUTPUT}\ngroup:rpm"
- OS_GROUP=`/bin/rpm -q --qf "%{NAME}" --whatprovides redhat-release | sed 's/-release.*//' | tr '[A-Z]' '[a-z]'`
+ OS_GROUP=`/bin/rpm -q --qf "%{NAME}" --whatprovides redhat-release | grep -vi 'freeing read locks for locker' | sed 's/-release.*//' | tr '[A-Z]' '[a-z]'`
REDHAT_VERSION=`/bin/rpm -q --qf "%{VERSION}" --whatprovides redhat-release`
case "$OS_GROUP" in
"centos" | "fedora" | "sl")
diff --git a/doc/server/plugins/probes/index.txt b/doc/server/plugins/probes/index.txt
index f22f405c1..95aa2d0ce 100644
--- a/doc/server/plugins/probes/index.txt
+++ b/doc/server/plugins/probes/index.txt
@@ -208,7 +208,7 @@ look something like:
<FileProbes>
<FileProbe name="/etc/foo.conf"/>
<Group name="blah-servers">
- <FileProbe name="/etc/blah.conf" update="true"
+ <FileProbe name="/etc/blah.conf" update="true"/>
</Group>
<Client name="bar.example.com">
<FileProbe name="/var/lib/bar.gz" base64="true"/>