diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/_templates/indexsidebar.html | 11 | ||||
| -rw-r--r-- | doc/appendix/guides/gentoo.txt | 73 | ||||
| -rw-r--r-- | doc/conf.py | 8 | ||||
| -rw-r--r-- | doc/development/index.txt | 1 | ||||
| -rw-r--r-- | doc/development/plugins.txt | 4 | ||||
| -rw-r--r-- | doc/development/setup.txt | 7 | ||||
| -rw-r--r-- | doc/development/unit-testing.txt | 25 | ||||
| -rw-r--r-- | doc/server/plugins/connectors/templatehelper.txt | 74 | ||||
| -rw-r--r-- | doc/server/plugins/generators/packages.txt | 40 | ||||
| -rw-r--r-- | doc/server/plugins/probes/group.txt | 2 |
10 files changed, 158 insertions, 87 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/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/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/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 276b73093..855a3c51c 100644 --- a/doc/server/plugins/generators/packages.txt +++ b/doc/server/plugins/generators/packages.txt @@ -51,7 +51,7 @@ member clients. | Yum | yum | | +--------+----------+--------------+ -.. note:: +.. note:: .. versionadded:: 1.2.0 @@ -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> @@ -567,7 +574,7 @@ You can also view the sources applicable to a client:: Type: yum URL: http://mirror.example.com/centos-6-x86_64-updates GPG Key(s): http://mirror.example.com/centos-6-x86_64-updates/RPM-GPG-KEY-CentOS-6 - + Name: centos-6-x86_64-os Type: yum URL: http://mirror.example.com/centos-6-x86_64-os @@ -662,17 +669,8 @@ It understands the following directives: * ``gpg_keypath``: The path on the client RPM GPG keys will be copied to before they are imported on the client. Default is "/etc/pki/rpm-gpg". -* ``import_gpg_keys``: The RPM release of an RPM GPG key cannot be - reliably and automatically determined without importing the key into - the server's key chain. If ``import_gpg_keys`` is "false" (the - default), the release of automatically-generated RPM GPG key entries - in the specification will be set to "any", which disables - verification of the release. (Version will still be verified.) In - practice, this is unlikely to be an issue, as the RPM version of a - GPG key is the key's fingerprint, and collisions are rare. If you - do encounter a GPG key version collision, you will need to set this - to "true", whereupon Packages will import the keys into the server's - key chain. Python RPM libraries must be installed for this to work. +* ``version``: Set the version attribute used when binding + Packages. Default is ``auto``. [yum] section ------------- 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") |